CLI reference

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.

--description <text> adds optional Home text to a generated Thing in its first commit. Use a few words that add context beyond the name; omit it when redundant. Whitespace becomes spaces; the limit is 200 characters. Empty text means no description.

For a manifested repository, --description must match the committed description; it does not rewrite thing.yaml. Metadata flags are only valid for an initial put. To change an existing description, use `thing set-description`.

Gateway on the computer answers as it answers your browser after sign-in, so the status, headers, and bytes show what a site, file, or service serves. The result does not show the security headers Recovery adds for browsers.

A private service sees a placeholder owner (emptyos-fetch), not your account, and a GET runs its code. Redirects are not followed.

A text body prints its first 64 KiB. Every complete body reports its size and SHA-256. Use --range to read a later part or to check byte-range support.

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.

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.

The description is one line of at most 200 characters that Home shows under the Thing's name. Pass "" to remove it.

On a Git-backed Thing, a real change commits only `thing.yaml` as one Change and keeps a running Thing reachable; the manifest path must be clean. A no-op creates no commit.

Creates ~/data/<id>/ with owner-managed dataset.yaml and imports/, plus an empty SQLite payload behind the protected runtime boundary. A service receives only declared payloads as EMPTYOS_DATASET_<ID>; EMPTYOS_DATA_DIR names its restricted /data view.

A bounded non-owner tool opens only this Database, without networking, in sqlite3 safe and read-only modes. A statement that writes, attaches, or touches files fails. Rows from every statement are returned in order; --json prints { id, rows, rowCount }. The default deadline is 120 seconds; --timeout accepts 1 to 600 seconds.

SQL is one quoted argument of at most 16 KB over the workstation transport. Use Database commands or a running Thing for Database access; do not open the guarded payload from the owner shell or copy SQLite files between machines.

Runs under the computer's mutation lock in the same bounded, non-networked, single-Database tool view. Statements execute in order and stop at the first error; wrap several in BEGIN/COMMIT for atomicity. --json prints { id, changes, lastInsertRowid }. The default deadline is 120 seconds; --timeout accepts 1 to 600 seconds.

Database changes are not Changes: nothing is committed to Git and Undo never touches ~/data. SQL is one quoted argument of at most 16 KB over the workstation transport.

Without --confirm this only previews: the directory, database size, and the Things that declare the Database. With --confirm <id> repeating the id, it deletes ~/data/<id> entirely.

There is no Undo for Databases. Removal is refused while a registered service still declares the Database; remove its declaration and update its registration first.

Every mediated mutation is one record: the command, its source (a paired client by label, Home with the owner, the resident shell, or the system), the agent process when known, the outcome, and the duration.

Actions are not Changes: use `empty changes --json` for committed Git history and Undo. `--json` returns the newest 50 records.

Without a change ID, undoes the newest change whose action is "undo" with no actionReason in `empty changes --json`; pass that ID to name it explicitly.

Only a clean Thing can be undone. Older and platform changes are history only; Undo offers one step back followed by Redo.

Without a change ID, redoes the newest change whose action is "redo" with no actionReason in `empty changes --json`; after Undo, refresh Changes to see it.

A new saved change replaces the prior Undo/Redo choice.

Words after -- are passed through unchanged and the computer's shell joins them with spaces and parses them again, exactly like `ssh host command...`. Quotes the local shell already consumed do not survive, so pass a command containing quotes, parentheses, $, *, pipes, or && as one quoted argument.

Prefer transported `empty` commands, including `dataset query` and `dataset exec`, whose arguments travel as structured data and need no remote quoting.

Copies the emptyos-computer skill that ships with this client to <dir>/emptyos-computer/, replacing an earlier copy. The default directory is ~/.agents/skills.

The client records each install. When a different client version runs, it refreshes every recorded copy that still exists and says so on stderr.

If another skill update is running, automatic refresh retries on a later command. An explicit install waits briefly, then reports a busy error if the other update is still running.

Read this skill before working on an EmptyOS computer. Pass its requirements to any worker you delegate to.

Prints the complete Markdown from this client package. No skill installation or computer connection is needed. This command runs offline and leaves client state unchanged.