CLI reference
Every empty command, from the same table as empty --help. Client 0.1.7, protocol 2.
Run every command from the workstation. The client decides whether it runs locally, on the computer over the tunnel, or as a git workflow across both.
--json, where a command lists it, returns one object. Failures print{"error", "code"}and exit 1.--computer <alias>before a command that works on a computer selects a profile other than the default.- A first word the client does not know is looked up in the computer's own command inventory and forwarded if registered there.
| connect <computer-url> [--as <alias>] [--label <label>] [--no-browser] | Connect this client to an EmptyOS computer.--as <alias> Local shorthand used to select this computer; defaults to the first part of its URL.--label <label> This client's display label on the approval and approved-agent screens; defaults to this machine's hostname.--no-browser Print the approval page URL without opening it in your default browser.empty connect vishal.emptyos.com
empty connect maya-chen.emptyos.com --as maya
empty connect jordan.emptyos.com --label "Jordan's AI Computer" |
| computers [--json] | List configured computers. |
| computer add <alias> --host <host> [--release-catalog <https-url>] [--json] | Add a computer by SSH host. empty computer add personal --host owner@personal.example |
| computer use <alias> [--json] | Select the default computer. |
| computer show [--json] | Show the selected computer. |
| computer update [--check | --resume <stage-name>] [--release <signed-release.json> | --catalog <https-url>] [--json] | Update Home, Gateway, CLI, Recovery, and system services as one signed EmptyOS release. empty computer update --check
empty computer update
empty computer update --resume stage.A1b2C3
empty --computer work computer update --release ./emptyos-release.json |
| computer remove <alias> [--json] | Remove a computer profile. |
| things [--json] | List Things on the selected computer. empty things
empty --computer work things --json |
| put <path> [--as <id>] [--name <name>] [--project <project-id>] [--public] [--json] | Put local content on the selected computer. A directory is the deployment boundary: every selected file becomes owner-served content and may become anonymous with --public. Prefer a ready build-output directory over a source repository root. A manifested repository may run its tracked ./prepare as trusted owner code on the computer before offline verification. empty put ./portfolio --as portfolio
empty put ./olive.jpg --as olive --public
empty put . |
| clone <id> [directory] [--json] | Clone a Thing for local work. |
| thing describe <id> [--json] | Inspect a Thing. |
| thing logs <id> [--lines <count>] [--json] | Read recent service logs. |
| thing assign <thing-id> <project-id> [--json] | Assign a Thing to a Project. On a Git-backed Thing, a real change commits only `thing.yaml` as one Change; the manifest path must be clean and unrelated edits are preserved but can temporarily block Undo. A no-op creates no commit. Detached HEADs and interrupted Git operations are refused. |
| thing unassign <thing-id> [--json] | Remove a Thing from its Project. On a Git-backed Thing, a real change commits only `thing.yaml` as one Change; the manifest path must be clean and unrelated edits are preserved but can temporarily block Undo. A no-op creates no commit. Detached HEADs and interrupted Git operations are refused. |
| thing start <id> [--json] | Start a service Thing. |
| thing stop <id> [--json] | Stop a service Thing. |
| thing restart <id> [--json] | Restart a service Thing. |
| thing remove <id> [--json] | Remove a Thing service registration. |
| thing recover-import <id> [--json] | Recover an interrupted Thing import. |
| thing recover-activation <id> [--json] | Recover an interrupted Thing activation. |
| share <id> --with <email> [--json] | Grant restricted access to a static Thing. empty share spending --with alice@example.com |
| unshare <id> (--with <email> | --all) [--json] | Revoke restricted access to a Thing. |
| shared [--json] | List links saved under Shared with me. |
| shared add <url> [--json] | Save a restricted-sharing link to this computer. |
| shared remove <url> [--json] | Remove a saved restricted-sharing link. |
| projects [--json] | List Projects. |
| project create <id> <name...> [--json] | Create a Project. |
| data [--json] | List registered Datasets. |
| data describe <id> [--json] | Inspect a Dataset. |
| status [--json] | Show computer health. |
| changes [--json] | List committed changes. |
| commands [--json] | List built-in and local commands. |
| hooks [--json] | List lifecycle hook events. |
| hook install <event> <path> [--json] | Install a hook from a path on the computer. |
| undo <change-id> [--json] | Undo one committed change. |
| expose <id> [--json] | Publish a Thing to anyone on the internet. |
| unexpose <id> [--json] | Make a Thing private. |
| ssh [-- <command...>] | Enter the computer or run a raw command. |
| skill install [--dir <path>] [--json] | Install the bundled agent skill into a skills directory. Copies the emptyos-computer skill that ships with this client to <dir>/emptyos-computer/, replacing an earlier copy. The default directory is ~/.agents/skills. empty skill install
empty skill install --dir ~/.claude/skills |
| --json | Show the complete computer overview as JSON. |
| --version | Show the client and protocol version. |
| help [command...] | Show command help. |