DX CLI
DXOS command line interface.
Installation
npm install -g @dxos/cli@main
Agent
See main docs at Agents
Running an agent as a system service
Start an agent as a system daemon via CLI command
Agent could be started as a system daemon via cli command:
dx agent start --system
This command will run an agent as launchd
service (macOS users) or as a systemd
service (Linux users).
Other useful commands:
dx agent list --system
dx agent restart --system
dx agent stop --system
Alternatively, manual setup could be used (see below).
Install agent as a launchd
service (macOS users) - manual setup
- Install DXOS CLI with steps in Installation section.
- Replace
??NODE_PATH??
in "./init-templates/org.dxos.agent.plist" with output of command dirname $(which node)
- Replace
??DX_PATH??
in "./init-templates/org.dxos.agent.plist" with output of command which dx
- Copy
./init-templates/org.dxos.agent.plist
-> ~/Library/LaunchAgents/org.dxos.agent.plist
- Run
launchctl load -w ~/Library/LaunchAgents/org.dxos.agent.plist
Stop agent started by launchd
- Run
launchctl unload -w ~/Library/LaunchAgents/org.dxos.agent.plist
- Remove
~/Library/LaunchAgents/org.dxos.agent.plist
Install agent as a systemd
service (Linux users) - manual setup
- Install DXOS CLI with steps in Installation section.
- Copy
./init-templates/dxos-agent.service
and ./init-templates/pre-dxos-agent.service
-> ~/.config/systemd/user/
- Run
systemctl --user daemon-reload
to make the systemd daemon aware of the service - Run
systemctl --user enable dxos-agent
to enable the service to start automatically - Optionally, run
sudo loginctl enable-linger {USERNAME}
to enable the service to start without user login (replace {USERNAME}
with the name of the user that will run the service) - Run
systemctl --user start dxos-agent
to start the service
Start agent with CLI
Agent is automatically started by each command that requires Client (to avoid this behavior use --no-agent
flag). You can use --profile
flag (default value is default
) to run agent in an isolated profile, and --foreground
to run agent in attached process.
dx agent start
see: dx agent start
Adding Agent to your Composer Identity
-
Go to Composer. And create a device invitation.
![Composer invitation](./public/composer-add-device.png)
-
Run halo join command in your terminal.
![CLI halo join flow](./public/cli-halo-join.png)
-
Proceed with invitation
Troubleshooting
- Make sure you are running the latest version of the shared worker in the browser. Go to the shared workers tab chrome://inspect/#workers, kill
dxos-vault
worker, then reload the Composer tab. - Restart your agent with
dx agent restart
. Also useful command dx agent stop --all
Danger Zone
- Reset Storage. Warning: Agent will lose its storage, and config file will be deleted
dx reset --force
Development
Multiple Profile configuration
Both the CLI and agents can be configured to use a given profile using either the --profile
flag or DX_PROFILE
environment variable.
The CLI will automatically connect to the agent using the given profile.
Local development
The CLI can be invoked out of the Git monorepo using the bin/dev
command.
Source the following script to set an alias for dx
that can be called from any directory:
cd packages/devtools/cli
. ../../devtools/cli/scripts/dev.sh
Example:
DX_PROFILE=test dx agent start --ws=4567
NOTE: The agent
will need to be recompiled after any changes.
Building
To build the CLI:
nx run cli:build --watch=true
Devtools
The agent can be configured to expose a Websocket port using the --ws
flag that can be connected to using DXOS Devtools:
To connect devtools, set the target
query parameter to the agent's websocket URL, e.g.,
https://devtools.dxos.org?target=ws://localhost:4567
Debugging
To enable logging, set LOG_FILTER
:
LOG_FILTER=info,agent:debug dx agent start -f
If the agent is run in background mode, log files will be created in /tmp/dx/run/profile/<profile name>/logs
To enable the node debugger, set NODE_OPTIONS
then open in VSCode (CMD-SHIFT-P "Attach to Node process").
NODE_OPTIONS="--inspect-brk"
Reporting errors
Run the following command to create a gist of the debug stats.
dx debug stats --json --no-agent | gh gist create