Resource Management
Manage Agent identities, project registrations and Agent-owned Sessions
City CLI manages Agent identities, Workspace registrations and Sessions. The bare city interface uses the same resource client as explicit commands. Resource commands discover the current CLI or Desktop host for their data root and verify its instance and root identity before calling its local management channel. Desktop management is independent of the City Remote HTTP setting.
Agent identities
city agent create --name Reviewer --id reviewer --model MODEL_ID
city agent list --query review
city agent list --loaded
city agent get reviewer --include-instruction
city agent update reviewer --description "Review changes" --instruction-file ./SOUL.md
city agent update reviewer --model MODEL_ID --if-revision HASH
city agent update reviewer --unset-model
city agent delete reviewer --yesCreation requires a name. The ID is generated from that name unless explicitly supplied; explicit IDs accept lowercase letters and digits separated by underscores. Creation does not initialize a project, register a Workspace or install project assets. Models may be omitted for configuration and history access. Sending requires an executable model.
Agent updates preserve existing system snapshots, explicit Session model overrides and running Turns. Sessions persist the creation-time default model ID separately from explicit model overrides, so release and restart restore the same selection. Older history without a reliable model ID remains readable and requires one explicit Session model selection before execution. Model labels are display text and are never used to guess an ID. session get exposes model_binding and model_selection_required. Online updates resolve the model before saving. Offline model validation is deferred. revision is a content hash; pass --if-revision to reject concurrent changes. A saved configuration that could not be applied returns partial_failure; retry the same update to apply it.
Deletion permanently removes the Agent-owned directory, including configuration, Sessions, archives, attachments, skills, logs and owned Power data. Active work, pending execution and strong Group, Task, Messenger, Token or Session references block deletion. Resolve references explicitly; deletion does not stop work or delete other resources.
Project registrations
city workspace register ./project --name Project
city workspace register /srv/project --ssh build-server --name Remote --initialize-dependencies
city workspace initialize WORKSPACE_ID
city workspace list --query project
city workspace get WORKSPACE_ID
city workspace update WORKSPACE_ID --name "Project name" --if-revision HASH
city workspace remove WORKSPACE_ID --yesLocal registration requires an existing accessible directory and resolves its real path. It does not create files. Registering the same path returns its existing ID; change its name with update. Existing aliases resolving to the same directory are reported as conflicts. The first release updates names only.
Removal releases idle runtime resources and removes the registration. Active execution or Shell processes block removal. Project files, Sessions, attachments and historical Workspace IDs remain. Sessions whose Workspace registration is missing can be browsed but cannot receive input. Registering that path again creates a new ID. Agent-private main Workspaces are hidden by default; workspace list --include-internal displays them read-only.
SSH registration validates an existing Linux/macOS remote directory through system OpenSSH. Add --initialize-dependencies to install missing Python 3.8+, ripgrep (rg) and POSIX ps on the remote host before registration. Use city workspace initialize WORKSPACE_ID to check and install dependencies for an existing SSH Workspace. Both installation options explicitly authorize remote package installation; tools already available are skipped. Linux uses an existing apt-get, dnf or apk and needs root or non-interactive sudo; macOS needs Homebrew. If installation is unavailable, ask an administrator to provide the tools on the non-interactive SSH PATH. Initialization uses a five-minute installation timeout and verifies the environment afterward. Failures report the package manager output; inspect remote state before retrying an interrupted installation. --ssh accepts a Host alias or user@host; absolute directories are resolved remotely. CLI strictly checks host identity: independently verify and trust it in system known_hosts, or use Desktop's explicit fingerprint confirmation. Identity combines the connection target and canonical remote root, so the same directory on different hosts registers separately. List and detail results include source; remote directories are not checked on the local machine. Rename and remove use the same commands, and removal preserves remote files and local history. SSH Shell runs with remote-user permissions without local Sandbox isolation. Disconnected commands and changes are never automatically replayed. See Desktop SSH projects.
Sessions
city session create --agent reviewer --workspace WORKSPACE_ID
city session list --agent reviewer --category work --limit 50
city session list --agent reviewer --category chat --origin-type agent
city session list --agent reviewer --archived
city session get SESSION_ID --agent reviewer --category work
city session history SESSION_ID --agent reviewer --limit 50 --include-internal
city session history SESSION_ID --agent reviewer --before-sequence 120
city session send SESSION_ID --agent reviewer --message "Review this project" --request-id REQUEST_ID
city session send SESSION_ID --agent reviewer --message-file ./request.txt --no-wait
city session stop SESSION_ID --agent reviewer --turn-id TURN_ID
city session archive SESSION_ID --agent reviewerAn address consists of the complete Agent ID, category and complete Session ID. Category defaults to work and accepts chat or work; origin type is a list filter, not an address. New ordinary Sessions use work/work and require an explicit registered Workspace ID or --workspace-path. Reading details or history never enters a Workspace or restores an executor. Archived history is resolved automatically. --include-internal includes canonical internal Messages without decoding private answers or opening attachments.
Lists use snapshot cursors online. The resource TUI provides next/previous pages and refresh; expired cursors return to the first page, and archival refreshes the list. Limits are 1–200. Keep all filters unchanged when supplying --cursor; expired cursors require a fresh first page. Offline lists support the first page only and return pagination_available: false; history uses --before-sequence to read older Messages. Archived lists do not accept --origin-type.
send normally waits for the Turn result. --no-wait returns after acceptance and leaves execution with the host. A stable --request-id deduplicates the same input in the same Session. A timeout or disconnected client does not stop an accepted Turn. The CLI checks the same request_id against canonical reception and the persisted completion journal without resending: recovered completion returns its result; otherwise error details report accepted/not_accepted and the known Turn ID. unknown is reserved for cases where neither the current host nor a safely coordinated offline reader can verify the outcome. Waiting for a question or approval returns interaction_required; respond through the host's interaction interface. stop conditionally stops the current Turn and cancels queued prompts. archive preserves data and delegates descendant Work archival to the SDK; it refuses busy nodes and can report partial completion after storage failure.
city agent chat reviewer --new-session --workspace WORKSPACE_ID
city agent chat reviewer --session-id SESSION_ID
city agent chat reviewer --session-id SESSION_ID --message "Continue" --jsonTTY chat can open the most recent active Session, or select an existing project for a new ordinary work Session. A supplied Workspace must match an existing Session's persisted directory. Scripts must supply --session-id, or --new-session with an explicit Workspace. One-shot chat supports message files, request IDs and --no-wait through the same send use case.
Host and offline access
macOS and Linux use user-private Unix sockets. Windows uses a named pipe with AES-GCM encryption and mutual HMAC frame authentication; the per-instance credential is stored in a current-user SID-only ACL directory created and verified through system PowerShell/.NET. A failed ACL or authentication check refuses management access. Offline configuration uses the same root lease protocol.
Existing CLI Env, Token and Power configuration writes are routed to the current host's resource coordinator. Offline writes hold the same root lease as Agent/Workspace management; Desktop configuration writes share the host coordinator. Token Agent references are rechecked inside the write transaction. Power artifact install/update/uninstall requires an offline root and holds the exclusive lease while replacing files; a running host refuses artifact replacement rather than loading a partially changed package.
Execution, creation, stopping and archival of Sessions require an explicitly started City host (city on or Desktop). Resource commands never start or take over a host. An unreachable, starting or incompatible host blocks operations instead of falling back to local execution.
Without a host, Agent and Workspace configuration and side-effect-free historical browsing are available. A root lease coordinates hosts and offline clients. Existing roots without a coordination descriptor require an explicit supported-host start before offline browsing. Queries never migrate schema, recover a pending configuration commit or repair an uncheckpointed database journal. Such states require explicit recovery through a writable host or configuration operation. A missing root returns empty lists without creating it.
Automation
Every resource command supports --root PATH, --json and a positive --timeout SECONDS. Root precedence is explicit option, DC_PLATFORM_ROOT, then the user data directory. Deletion/removal in JSON or non-TTY mode requires --yes. JSON mode does not prompt or emit model fragments.
Standard output contains one JSON object followed by a newline:
{"schema_version":1,"success":true,"command":"agent.list","data":{"items":[],"total":0},"error":null,"meta":{"root_path":"/data/city","host":null,"source":"local","observed_at":"2026-11-06T00:00:00.000Z"}}Failures provide error.code, message, retryable and details. Partial outcomes and accepted Turn addresses are carried in error details. Runtime state is unknown offline. DTO times are UTC ISO strings; canonical history retains SDK message structure and timestamps.
| Exit | Meaning |
|---|---|
| 0 | Success, including empty lists and no change |
| 1 | Unclassified internal failure |
| 2 | Usage or validation failure |
| 3 | Resource not found |
| 4 | Busy, revision, reference or interaction conflict |
| 5 | Host, coordination or capability unavailable |
| 6 | Permission failure |
| 7 | Operation or waiting timeout; accepted work can continue |
| 8 | Turn failed or stopped |
| 9 | Partial save, application or lifecycle failure |
| 130 | User interruption or cancellation |