Documentation menu

// Reference

CLI reference

This page lists the commands of the artifactbridge command-line tool. A script makes this page from the built-in help of the tool.

To see the same help in a terminal, run artifactbridge help. To see the help for one topic, run artifactbridge help <topic>. Commands that only the desktop app runs and retired installation commands are not on this page.

Skill counting needs the workspace switch and your own switch on. Learn what is counted, including privacy controls, coverage and limits. Existing skill installation commands do not report loads.

artifactbridge [--dry-run] <command> [options]

Getting started

(no command)

Show the active local connection or the next sign-in step.

login [--server URL] [--workspace W] [--install-clients LIST] [--agent]

Start browser OAuth for one environment session. --agent connects the harnesses as agents of the signed-in person (server and cron installs).

login [--server URL] [--workspace W] [--install-clients LIST] [--agent] --no-browser --callback-port PORT

Sign in over SSH. Forward PORT from the computer with your browser (ssh -L PORT:127.0.0.1:PORT <host>), then open the printed link there. The command opens no browser, listens on 127.0.0.1 only, never tries another port, and waits until the sign-in finishes or times out.

login [--server URL] --token-env VAR [--install-clients LIST]

Register a headless CI token environment variable.

logout

Remove the active environment session.

auth reconcile [--json]

Retry pending grant-family revocations for all environments.

status [--json [--env | --workspace]]

Show connection, workspace, client selectors, session, and tray state.

doctor [--report]

Diagnose the install. Use --report for a pasteable summary.

Everyday

inbox

Show the needs-you feed for the connected workspace.

inbox seen|unseen|dismiss KIND ID [--json]

Change your own state of one Inbox item. A dismissal prints the stamp for undo.

rooms list|watch|events

List joined Agent Rooms, read events, or watch for activity.

docs import PATH|- [--folder F | --no-folder] [--skill | --no-skill] [--visibility private|workspace] [--recursive [--select Q]] [--json]

Import local Markdown for human review. A file whose name contains "skill" is registered as a skill by default; --no-skill turns that off.

docs import --repo OWNER/NAME [--ref R] [--path SUB] [--json]

Import a GitHub repository for human review.

rooms upload-image --room ID PATH... [--json]

Upload local images to an Agent Room and print Markdown for a message.

docs upload-image PATH (--folder F | --no-folder) [--title T] [--working] [--json]

Create a Library image from a local file.

docs archive|unarchive ID [--json]

Archive or unarchive a document you can edit. Archive is not delete.

docs duplicate ID [--json]

Copy a document you can read into a new managed document in the same folder.

docs update ID --expected-version VERSION_ID --file PATH|- [--summary TEXT] [--json]

Write a new version of a managed Markdown document. A governed document gets a proposal for human review.

docs subscription ID --mode watching|muted|default [--json]

Watch or mute a document for yourself, or return it to the workspace default.

companion conversations|rooms|tools

Organize your companion conversations: titles, Agent Room bindings, wake policy, and tool picks.

profile get|set-name|photo|avatar-color

Read or change your own name, photo, and avatar color.

preferences get|theme|coach-mark

Read or change your own theme and coach marks.

agents list|create|update|share|send|conversations

List your agents, create and edit agents that work in one fixed Space, or set who can use them. Send an agent a task in a room, or talk with an agent in a private conversation.

workflows draft|list|run|pause

Draft, list, run, or pause your workflows. Only the owner activates a draft, in the app.

spaces read|update|pull

Read a Space with its revision, change its description, skills, and references at that revision, or pull its readable files into a new directory.

workspace list|use|clear

List or select the workspace for this environment.

skills list|install|uninstall|sync|reconcile

Manage workspace skills for supported agent clients.

skills scan [--json]

Scan documented user skill roots. Nothing is sent.

skills list --local [--json]

Read the last local scan without walking skill roots.

skills inspect ID [--json]

Safely reread and show inert, masked local text and retained file metadata.

skills add-to-workspace ID [--name SLUG] [--folder UUID] [--agents-can-use yes|no] [--direct-changes yes|no] [--access workspace|private] [--dry-run] [--json]
skills propose-local ID --stdin-json [--dry-run] [--json]

Prepare an exact private preview. --dry-run uses cached data only and does not stage.

skills add-to-workspace PREVIEW_ID --confirm DIGEST [--json]

Create the reviewed SKILL.md as a document and register it as a skill, as the web New skill dialog does.

skills add-to-workspace --document UUID --name SLUG --skill-check-reason - [--json]

Read your reason from stdin (at most 1000 characters) when the skill check needs one.

skills add-to-workspace --document UUID --discard [--json]

Delete the document that Add to workspace created when you give no reason.

skills propose-local PREVIEW_ID --confirm DIGEST [--json]

A person sends approved bytes for review. Retry and Check keep the original key.

skills local check|retry|acknowledge PREVIEW_ID --confirm DIGEST [--json]

Observe, retry unchanged, or acknowledge the final outcome of a proposal.

skills local refresh [--json]

Explicitly refresh the authorized caller catalog. Ordinary list never uses the network.

skills keep-local ID [--undo] [--json]

Keep a group under a verified account/workspace scope.

skills use-workspace-version ID --to WORKSPACE-SKILL [--confirm DIGEST] [--json]
skills use-workspace-version ID --status|--recover [--json]

A person moves the whole local folder aside and installs the workspace version.

skills link-to-workspace ID --to WORKSPACE-SKILL [--json]

Make a local folder the installed copy of the workspace skill it is.

skills changes list|show|send|keep|discard
skills reviewer status|on|off
skills usage [status|on|off]

Review a skill change that a local tool staged, then send it for review.

Maintenance

setup status|plan|apply

Inspect or reconcile coding-tool setup as one CLI-owned transaction.

tools status|install|login|auth-status|report

Install a coding-tool CLI or run its own sign-in from the desktop app.

update [--dry-run]

Update through the recorded installation owner. AUR installs update in Terminal.

update status [--json]

Show the verified update owner, capability, release identities, and health.

update auto on|off

Manage verified automatic toolkit updates.

update preference on|off [--json]

Record the automatic application update choice. A person decides.

update system status [--json]

Show the machine package update policy of the Linux DEB or RPM package. Read-only.

update system enable|disable [--json]

Change the machine package update policy for all users. An administrator decides.

installation repair-homebrew-cask --brew-prefix PREFIX [--json]

Restore Homebrew ownership for the installed Cask.

tray install|status|uninstall

Manage the desktop tray installation.

telemetry enable|disable|status|hermes

Manage status-only local telemetry collection.

uninstall

Remove owned ArtifactBridge files and configuration.

Agent integration

agent ...

Manage Agent Room hooks, runtime consent, wake policy, coding-tool accounts, repository connections, and tray status. See 'agent --help'.

Global

help

Show the main help or help for one topic.

version

Print the bridge version.

--dry-run

Preview changes without modifying anything (where supported). help <topic> or <group> --help shows every other command.

Interactive network commands can print one availability notice per day on stderr.

Command details

This part gives the options of each command, grouped by the first command word.

auth

artifactbridge auth reconcile [--json]

Retry pending grant-family revocations for all environments. --json prints pending, revoked, and error lists.

logout

artifactbridge logout

Remove the active environment session.

status

artifactbridge status [--json [--env | --workspace]]

Show connection, workspace, client selectors, session, and tray state. --env and --workspace select stable machine payloads and require --json.

doctor

artifactbridge doctor [--report]

Diagnose the install. --report prints a pasteable summary. Warns for each Hermes profile with bound chats whose room wakes are not ready; details: agent hooks status --hermes --hermes-profile NAME --json.

env

artifactbridge env list [--json]

List environment profiles.

artifactbridge env use|attach

Switch or attach an environment profile.

workspace

artifactbridge workspace list

List workspaces accessible in the active environment.

artifactbridge workspace use <slug-or-id>

Select an accessible workspace for CLI and MCP clients.

artifactbridge workspace clear

Remove the selector when the environment has one workspace.

update

artifactbridge update [--dry-run] [--server URL]

Update through the recorded installation owner. An AUR (pacman) install is not updated here. The command prints the yay or paru command to run in Terminal, or the manual AUR steps when neither helper is installed.

artifactbridge update status [--json]

Check through the verified installation owner. The JSON output separates running, installed, and latest release identities. Package-managed owners report the package manager and never claim automatic apply support. When the AUR is unreachable, an AUR install reports its last AUR read with that read's time. A read older than 24 hours is stale. A Homebrew install adds a package_update object (schema 1): effective policy, phase, candidate, reason_code, and next_action. An attempt that waits (reason_code busy or network_unavailable) adds retry_after, in Unix seconds; no automatic retry starts before it. Only effective_policy says whether automatic updates run. An unfinished or unknown result is not success; read the status again.

artifactbridge update preference on|off [--json]

Record the automatic application update choice for this user on this computer. Off stops later automatic updates. An update that already started still finishes. A brew upgrade that you run yourself is outside this choice. This is a person's choice: an agent gets requires_person and nothing changes.

artifactbridge update system status [--json]

Show the automatic package update policy for all users of this computer (Linux DEB or RPM package). It only reads: it never prompts, asks for a password, or changes the policy or the timer. The JSON output is a package_update object (schema 1) with policy_scope machine. desired_policy is the recorded choice; only effective_policy says whether automatic updates run. A fresh administrator install records on; an upgrade never turns it on; a saved off stays off; a DEB purge forgets the choice; an RPM erase keeps it. effective_policy is on only after the update timer is confirmed enabled and active. Until the automatic package transaction is qualified, it always reports unsupported with package_api_unqualified, whatever the recorded choice, and no package changes. The status also shows policy_action_hint (authorized, challenge, unavailable, or unknown). The hint only says whether to offer the change; it grants nothing.

artifactbridge update system enable|disable [--json]

Turn automatic package updates on or off for all users of this computer (Linux DEB or RPM package). Your system asks for an administrator password; the local polkit action org.artifactbridge.update-policy decides. A canceled or refused prompt changes nothing (authorization_required). A failed timer start fails the change. This is a local administrator's choice: an agent gets requires_person before any prompt, and nothing changes.

artifactbridge update apply

Install the verified application update now through the installation owner. An agent can run it when a person asks. It never changes the automatic choice.

artifactbridge update restart

Restart into the verified installed application and check its exact version.

artifactbridge update auto

Show verified automatic toolkit-update consent.

artifactbridge update auto on

Enable verified automatic toolkit updates.

artifactbridge update auto off

Disable verified automatic toolkit updates.

installation

artifactbridge installation repair-homebrew-cask --brew-prefix PREFIX [--json]

Restore Homebrew ownership when the prefix link resolves to this application.

skills

artifactbridge skills list [--json]

List registry skills and local install state. --json has a stable machine-readable shape for trusted local consumers, such as the tray app. CHECK shows the AB check of the version you get. No issues found is not proof of safety.

artifactbridge skills reconcile [--json]

Move copies of deactivated skills to ArtifactBridge Trash, and restore them when the skill is active again. Exit 0: done or nothing to do. Exit 3: a copy was busy, failed or has a conflict; --json names it. Exit 1: the skill list failed.

artifactbridge skills safety <slug> [--json]

Show the AB check of the skill version you get: result, rules version, date, and findings as file:line and rule. A read: nothing changes. The tray and this command never accept, allow, or retire a skill.

artifactbridge skills scan [--json]

Scan supported local skill folders only when you ask. Nothing is sent. Local IDs come from the scan.

artifactbridge skills list --local [--json]

Read the saved local inventory. It does not scan again. A workspace comparison that is not available is reported as unknown.

artifactbridge skills inspect <local-id> [--json]

Show the local SKILL.md as inert text, with retained file names and sizes. Works offline. Values that look like secrets are masked.

artifactbridge skills add-to-workspace <local-id> [--dry-run] [--name <slug>] [--folder <UUID>] [--agents-can-use yes|no] [--direct-changes yes|no] [--access workspace|private] [--json]

Prepare exact SKILL.md bytes privately. --dry-run uses local/cached data only, with no network or staging writes. Other files stay on this computer. The New skill settings need server support; a setting you omit takes the folder default. Private access needs private documents in the workspace.

artifactbridge skills propose-local <local-id> --stdin-json [--dry-run] [--json]

Read {"to":"workspace-skill-slug","why":"optional reason"} from bounded JSON stdin. An agent can run --dry-run. Preparation needs a genuine authorized catalog and the server capability.

artifactbridge skills add-to-workspace <preview-id> --confirm <digest> [--json]

Create the approved preview as a workspace document and register it as a skill, as the web New skill dialog does. Nothing is installed on this computer. A workspace skill with the same name refuses (name_taken) before anything is written. Results: created, needs_reason, needs_reader, checking, name_taken. The old name propose-to-team still works for one release.

artifactbridge skills add-to-workspace --document <uuid> --name <slug> --skill-check-reason - [--json]

When the result is needs_reason, read your reason from stdin (at most 1000 characters) and register the skill with it. The reason is not saved on this computer. A reason the check does not take returns needs_reason again with fresh findings.

artifactbridge skills add-to-workspace --document <uuid> --discard [--json]

When you do not give a reason, delete the document that Add to workspace created. The server deletes only a document you created that is still at version 1 and is not a skill (otherwise not_discardable). Result: discarded.

artifactbridge skills propose-local <preview-id> --confirm <digest> [--json]

A person sends the approved change against its reviewed workspace head. Missing lifecycle/producer support keeps this unavailable.

artifactbridge skills local check|retry|acknowledge <preview-id> --confirm <digest> [--json]

For a proposal: Check observes the saved request. Retry uses only its original key and bytes. Acknowledge a final outcome before preparing a changed request.

artifactbridge skills local refresh [--json]

Refresh the caller-visible catalog explicitly. The desktop offers Check now for observation and Retry for the same saved request. An unknown outcome never creates a new key.

artifactbridge skills keep-local <local-id> [--undo] [--json]

Keep a local decision, or undo it, when a verified workspace identity is available.

artifactbridge skills use-workspace-version <local-id> --to <workspace-skill> [--json]

Show the exact replacement and its digest: the workspace version, the whole folder that moves aside, the tools that read it and where the workspace version is installed. Nothing is changed.

artifactbridge skills use-workspace-version <local-id> --to <workspace-skill> --confirm <digest> [--json]

A person moves the whole folder aside and installs the confirmed workspace version. A changed folder, workspace version, account or workspace is refused before anything moves. The moved-aside folder is kept.

artifactbridge skills use-workspace-version <local-id> --status|--recover [--json]

Status only reads. Recover finishes or undoes an interrupted replacement and keeps your files. An agent cannot run this command.

artifactbridge skills link-to-workspace <local-id> --to <workspace-skill> [--json]

A person records the local folder as the installed copy of the workspace skill of the same name. No file in the folder is written or moved. A folder equal to the workspace version gets updates; a folder that differs shows in 'skills changes list --local' as a local edit. An agent cannot run this command.

artifactbridge skills changes list [--json]

List the skill changes that a local tool staged for approval, with their exact lines. A read: nothing leaves this machine. A staged write that cannot become a proposal is reported in --json only.

artifactbridge skills changes list --local [--json]

List metadata for local edits to installed skills and ArtifactBridge guidance, without a network request.

artifactbridge skills changes show <id> [--json]

Show a staged or local skill change against the current team version, and its confirm digest.

artifactbridge skills changes send <id> --confirm <digest> [--reason <text>] [--json]

Send the change that you saw for review as one proposal. Anyone in the workspace can accept it in the Inbox. The digest comes from 'show'. A change or a workspace version that moved since is refused. A local edit of a working skill that you created updates the shared skill instead; 'show' names the action.

artifactbridge skills changes discard <id> --yes [--json]

Remove the staged change from the tool's pending folder. Local only.

artifactbridge skills changes keep <id> [--json]

Keep a local edit on this machine and leave updates paused. Works offline.

artifactbridge skills changes discard <id> --confirm <digest> [--json]

Back up a local edit, then restore the current team or built-in version. Added files stay in place.

artifactbridge skills reviewer status [--json] [--refresh]

Show the skill reviewer switches, the unsent suggestions, and the recent reviews on this computer. --refresh reads the workspace owner switch again.

artifactbridge skills reviewer on [--json]

Turn the skill reviewer on for this computer. It is on by default.

artifactbridge skills reviewer off [--json]

Turn the skill reviewer off for this computer. A running review stops, and unsent reviewer suggestions are deleted.

artifactbridge skills usage [--json]

Show your skill use on this computer in the last 30 days: session-days, last used day and tools per skill. It also lists the skills installed here with no observed use, or says why this computer can't tell, and coverage per tool. It reads only this computer's records, with no network. Your use across computers is in the web app.

artifactbridge skills usage status [--json]

Show whether your skill use is counted in the current workspace, as the server says, and any unconfirmed change.

artifactbridge skills usage on [--check] [--json]

Count your skill use in the current workspace. Needs your own sign-in; an agent is refused.

artifactbridge skills usage off [--yes] [--check] [--json]

Stop counting your skill use in the current workspace and delete your counts there. Asks Continue? [y/N] at a terminal; --yes skips it. Without a terminal and without --yes it exits 2 and changes nothing. If the reply is lost, it exits 75 and keeps the request key. --check looks that key up without changing anything; running the same command again sends the same key, so the change applies once.

artifactbridge skills install <slug> [--clients claude,codex,grok,opencode,hermes,openclaw] [--discard-local] [--move-aside] [--json]

Install a workspace skill for the selected clients. It prints what the skill can do first. A client whose coding tool is not on this machine is refused (tool_not_detected) and nothing is written. A copy with local edits is kept as it is (local_edit_held, exit 3). --discard-local backs it up, then installs. A folder that ArtifactBridge did not install is refused (target_not_owned). --move-aside moves it into the state folder, then installs. A person runs --discard-local and --move-aside; an agent is refused (requires_person).

artifactbridge skills retry <slug> [--clients claude,codex,grok,opencode,hermes,openclaw] [--discard-local] [--move-aside] [--json]

Re-run a failed install.

artifactbridge skills update [<slug>] [--discard-local]

Re-pin installed skills whose content changed or that carry a pending hub Update intent. A copy with local edits is kept as it is. A named skill exits 3 (local_edit_held); --discard-local backs it up, then updates. It prints what each update adds first.

artifactbridge skills capabilities <slug> --json

Show what a skill can do in the files you receive: each line, its values, and where AB found it (Stated or Found, file and line). A read: nothing changes. The values come from the skill's files; AB can miss things.

artifactbridge skills uninstall <slug> [--clients claude,codex,grok,opencode,hermes,openclaw] [--discard-local] [--cancel-request]

Remove exactly what install wrote. Files that you added stay. A copy with local edits is kept unless you add --discard-local, which backs it up first. A skill your workspace requires is refused (required_by_workspace, exit 5). A Preinstalled skill stays removed from that tool on all your machines. --cancel-request also cancels your install request on every tool (line 'skills cancel <slug>: ...').

artifactbridge skills restore-backup <slug> [--clients c] [--at <id>] [--json]

Put back the newest backup of a copy, or the backup --at names. Works offline. Refused unless the copy is unchanged or its folder is gone; a file that you added is never overwritten (restore_conflict).

artifactbridge skills repair <slug> [--clients c] [--json]

Put back the files of a copy that were deleted, as ArtifactBridge installed them. Works offline. Files you changed or added stay as they are, and the installed version does not change.

artifactbridge skills link [<slug>...] [--clients LIST] [--yes] [--json]

Link skill copies installed before this update to the selected workspace, so updates can check them again. Lists the copies first; --yes links them. A copy with no install in this workspace is linked only when you name it. A copy that the selected workspace does not list is never linked: select its workspace, then run again.

artifactbridge skills sync [--install-clients LIST]

Refresh skill and context files without MCP configuration edits.

artifactbridge skills sync --auto [on|off] [--interval 30m] [--clients claude,codex,grok,opencode,hermes,openclaw]

Show or change automatic skill-refresh consent. On by default: a browser login enables it when no choice is recorded. An explicit 'off' is recorded and is never re-enabled automatically. One scheduler entry runs each job that has consent.

artifactbridge skills sync --auto clients <claude,codex,grok,opencode,hermes,openclaw> [--json]

Set the tools whose workspace skills stay current. Never changes the refresh consent.

artifactbridge skills expected [--report] [--json]

Show the skills your workspace expects on this machine. Writes no skill files. --report also sends this machine's status report (skills, versions, auto-sync state; no paths or content).

artifactbridge skills apply-workspace [--dry-run] [--json]

Install the skills your workspace expects on this machine now, also when automatic refresh is off. It never changes the refresh consent. --dry-run prints the plan and changes nothing.

tray

artifactbridge tray repair [--tag TAG] [--format auto|native|appimage] [--yes] [--dry-run]

Preview and confirm an owned Linux tray repair.

artifactbridge tray uninstall

Remove exactly what tray install created.

artifactbridge tray status [--json]

Compare the installed tray build with the latest stable release.

artifactbridge tray events watch [--consumer UUID] [--once] [--json]

Hold one WebSocket to the server and print one content-free NDJSON line per wake signal. The tray supervisor runs this stream to trigger immediate polls. The command reconnects with built-in backoff. --consumer asks for the doorbell of that tray updates consumer. A room_activity line then names a room or no room; each line is a hint to read tray updates, never a change itself. --once exits 0 after the first signal. The output is always NDJSON. --json is the explicit form.

artifactbridge tray updates begin|read|ack|compare|validate --consumer UUID [--cursor TOKEN] [--through TOKEN] [--progress TOKEN] [--limit N] [--snapshot] [--access-revision N] [--room UUID]... --json

Replay this credential's tray change stream for one device through artifactbridge_read_tray_updates. Rows carry room ids and flags only. read takes --cursor and an optional --through bound (default: the head). read --snapshot during a bootstrap reads one page of up to 200 rooms (room id, attention, pending, access revision); --cursor is the previous next_page. Resume the stream from its boundary. ack takes --progress, or as --cursor the feed receipt or a compare head taken before a complete feed refresh. Ack only after durable processing. Ack never marks a room read. After the bootstrap snapshot is stored, ack the begin boundary as --progress to end the bootstrap. validate takes the held rooms (--room, 1 to 16) and --access-revision. Drop a held room that is absent from rooms. On access_revision_changed, repeat the reads. A retry status or an error proves nothing about a room. An answer with an unknown field or another schema fails with reason unsupported_server; nothing falls back.

telemetry

artifactbridge telemetry enable [--clients claude,codex,grok,hermes] [--service-manager native|external] [--request-stdin] [--json]

Enable the status-only local relay. For claude, codex and grok, the tray supervises the relay; for hermes, a user service runs the relay, and telemetry disable and telemetry remove stop that service. With hermes, --service-manager external hands the relay to your own supervisor (for example supervisord, Docker or runit) instead: enable then needs no systemd, launchd or Task Scheduler and starts nothing. It saves consent and prints the command for your supervisor (see telemetry relay run). Without the option, the saved choice stays; a new setup is native. To switch, run telemetry disable, remove the old service or supervisor entry, check that the relay stopped, then enable with the new choice. Otherwise enable returns service_manager_conflict (exit 2) and changes nothing. With hermes, the relay reports Hermes token counts and cost estimates for chosen profiles. A person sets it up in a terminal that they opened themselves. An agent credential, or a command that an agent started, is refused with exit 3 (human_consent_required) before any change. A sign-in saved by login --agent is the person's own sign-in; do not sign in again to enable reporting. --json applies to hermes only. To renew Hermes consent, run telemetry enable --clients hermes again. It lists each saved profile with its role, store path and state. Only the ready profiles that you confirm are renewed. A saved profile that can't report is named before you confirm and is removed from reporting; choose it again later to add it back. Type r to check the stores again; that changes nothing. If a store changed after you reviewed it, nothing is renewed and the list shows again. Only one store of each profile name can be selected. The confirmed-request form is telemetry enable --clients hermes --request-stdin --json. It reads one JSON object (at most 64 KiB and 128 profiles), with schema:1, intent:enable|renew|change_profiles, workspaceId, expectedConsentRevision, profiles:[{name,selectionId,role}], and confirmed:true. Use exact handles from telemetry hermes profiles or, for a saved profile, from telemetry status, and the current status revision (0 before first consent). A saved store that discovery no longer lists is accepted while it is ready; a store that can't report fails with profiles_changed. Roles must be explicit: pm, designer, tech_lead, engineering_manager, engineer, reviewer, qa, researcher, or JSON null. Unknown fields and omitted roles fail. Enable requires absent or Off consent; renew and change_profiles require On or paused consent, including expiry. A changed state or revision requires a refresh and new confirmation. Do not resend an old request. Renew confirms the whole mapping; change_profiles replaces the whole Hermes set. Active other clients stay selected; Hermes-only enable does not restore clients stopped by a whole-relay disable. A person confirms the workspace, host, profiles, roles, disclosure, expiry and no-backfill rule first. Only run this yourself: the CLI cannot tell your confirmation from a script that uses your sign-in. This command does not sign in or change the account in use. If the workspace, consent or profiles changed, read telemetry status again and confirm again. If enable returns provisioning_outcome_unknown, run telemetry status; if Hermes is not On, run telemetry enable --clients hermes again. If enable returns local_state_unavailable after the server granted access, run telemetry status. If status works, note the clients it lists, run telemetry disable, then run telemetry enable --clients with those clients and hermes (for example --clients codex,hermes). If status also returns local_state_unavailable, the local reporting files in the ArtifactBridge state folder (telemetry/) cannot be read; make them readable first. If the service did not start after a saved grant, run telemetry hermes restart.

artifactbridge telemetry bind --client hermes --profile NAME --session ID --room REF [--json]

Bind one Hermes session of a selected profile to a Room. Only bound sessions report usage. --room takes a room UUID or a room key. A person or an agent may bind; neither turns reporting on. A session's Room never changes: another Room fails with binding_conflict. Start a new session for it. Repeating the same binding changes nothing. A delegated child reports through its parent's binding. Bind before the session uses a model. A session with no usage yet counts from zero; a session with usage counts from the next reading. The check cannot see a model call that is already running: its usage can still be counted.

artifactbridge telemetry plugin install --client hermes --profile NAME [--json]

Write the optional artifactbridge-binding plugin into a selected Hermes profile. It records which profile each session starts in, so a delegated child session can report under its own selected profile. It sends nothing. The command never enables it: add it to plugins.enabled in the profile's config.yaml yourself.

artifactbridge telemetry disable [--json]

Stop local collection and revoke relay access. Collection stops on this computer at once. If the server cannot be reached, the revocation stays pending and the next telemetry disable retries it, also after telemetry remove. A person can disable a Hermes setup with their own sign-in or with no sign-in at all, also after logout. An agent credential, a sign-in that cannot be confirmed, or a command that an agent started gets human_consent_required (exit 3) and nothing changes. If the revocation stays pending, reporting is still off on this computer; no sign-in is needed to keep it off. This stops the whole relay, including non-Hermes clients. A consent change while waiting returns consent_changed (exit 2) without stopping or revoking the new setup. Refresh status and confirm again.

artifactbridge telemetry status [--json]

Show relay health, queue, upload, and drop metadata, the CLI version, who is signed in and the Hermes reporting state. For Hermes, it lists each saved profile with its role, store path and state: ready, store not found, can't open the store, store busy, Hermes version not supported or couldn't check. Status changes nothing on this computer. If the local reporting setup cannot be read, status returns local_state_unavailable (exit 1). After disable, status still shows the Hermes destination, the consent revision and the time of the last usage the server acknowledged. Old credential cleanup shows counts, never IDs: "can't finish" is an old credential whose saved ID is invalid; it is never sent and never retried. "waiting to be revoked" is a valid ID that the next telemetry disable retries. In --json, oldCredentialCleanup has pendingCount, invalidIdCount and entries (outcome invalid_id or pending, revoked, retry); ingestCredentialConfigured says whether a current credential is saved. Only pending IDs set serverRevokePending.

artifactbridge telemetry hermes profiles [--json]

List Hermes profiles on this computer with each store path and its state: ready, or why it can't report. Reads no usage and changes nothing.

artifactbridge telemetry hermes restart [--json]

Start the Hermes reporting service again under the current consent. A person runs it; an agent credential or a command that an agent started gets exit 3. Expired consent, another workspace or a failed start changes no consent. With an external supervisor it starts nothing: it returns service_managed_externally (exit 2) and the command to supervise. Restart the supervisor entry instead.

artifactbridge telemetry hermes bind-open --request-stdin --json

The request a future binding plugin sends when Hermes opens a session. It reads one schema-1 JSON object from stdin: profileHome, sessionId, openId and reason, and nothing else. Automatic card binding is not available in this version: a valid request returns automatic_binding_not_ready (exit 2) and reads, binds, records and sends nothing. An invalid request returns invalid_request (exit 2). To bind a session now, use telemetry bind.

artifactbridge telemetry hermes workstreams list [--json]

List the Hermes workstreams on this computer and the Room of each. A workstream is one tenant on one Kanban board in one Kanban database. Reads only local files and changes nothing. The registration of each is live or removed. A removed workstream keeps its owner and revision; its Room is null (a dash in text) and its state is null. A live one has one of these states: kanban_db_missing: the database path cannot be read or is not a file. kanban_db_replaced: the path now names another file than the one set, or goes through a link. waiting_for_consent: Hermes reporting is off or has expired. A person turns it on with artifactbridge telemetry enable --clients hermes. workspace_mismatch: Hermes reporting goes to another workspace than the one that set this Room. Nothing reports here until they match. census_pending: the database, consent and workspace checks pass. It waits for automatic card binding, which is not available yet. Nothing to do. For kanban_db_missing or kanban_db_replaced, set the Room for the database's current canonical path. Automatic card binding is not available yet, so no workstream is active and no card usage reports.

artifactbridge telemetry hermes workstreams set --board BOARD --kanban-db PATH --tenant TENANT --room UUID --expected-revision N [--json]

Set the Room for new card sessions of one workstream. Set it once when you set up the work. A person or an agent may set it; it does not turn reporting on, select profiles or change consent. Give the exact board slug, the canonical absolute database path, the exact tenant and the Room UUID. You must be able to read the Room. Use --expected-revision 0 only for a workstream that never had a Room, and the listed revision for a change. stale_revision (exit 1) means it changed: list again and use the current revision. workstream_owned_elsewhere (exit 3) means another member or workspace set it. selected_token_unavailable (exit 2) means the selected token variable is not set or is empty; the saved sign-in is not used. Setting a Room does not turn on reporting yet: automatic card binding is not available.

artifactbridge telemetry hermes workstreams remove --board BOARD --kanban-db PATH --tenant TENANT --expected-revision N [--json]

Remove the Room of a workstream that you set. Sessions that started earlier keep their Room. The removal keeps its revision: to set a Room again, use that revision, not 0.

artifactbridge telemetry remove

Stop collection and remove only owned relay state. A person can remove a Hermes setup with their own sign-in or with no sign-in at all, also after logout. An agent credential, a sign-in that cannot be confirmed, or a command that an agent started gets human_consent_required (exit 3) and nothing changes. Remove turns reporting off and records the owed revocation before it contacts the server. With an external supervisor, remove waits for the relay to end before it deletes files. If the relay does not end, remove fails and deletes nothing; stop the supervisor entry, then run it again.

artifactbridge telemetry relay run

Run the Hermes relay in the foreground for an external supervisor. Run it as the user who ran telemetry enable, with the same HOME (or AB_STATE_DIR), so it uses the same state folder. It exits 0 when reporting is off, removed or renewed; restart it only on failure, after a renewal or after enable. A second relay for the same setup fails (exit 1). Status shows service manager external and running only while this relay holds the setup. disable and remove do not change the supervisor entry; remove it yourself. The examples are for the user me with the home folder /home/me. A supervisord program section:

[program:artifactbridge-relay]
command=/home/me/.local/bin/artifactbridge telemetry relay run
user=me
environment=HOME="/home/me"
autorestart=unexpected
exitcodes=0

A runit run script:

#!/bin/sh
exec chpst -u me env HOME=/home/me \
  /home/me/.local/bin/artifactbridge \
  telemetry relay run

A runit finish script, so that runit does not restart a clean exit:

#!/bin/sh
if [ "$1" = 0 ]; then sv down .; fi

A Docker command. It runs the relay as the same user, with the home folder mounted at the same path and HOME set to it. IMAGE is an image that can run the artifactbridge binary from that folder:

docker run --detach \
  --restart on-failure \
  --user "$(id -u me):$(id -g me)" \
  --volume /home/me:/home/me \
  --env HOME=/home/me \
  IMAGE \
  /home/me/.local/bin/artifactbridge \
  telemetry relay run

rooms

artifactbridge rooms status [--json]

Show local Agent Room lifecycle state.

artifactbridge rooms list [--runtime NAME] [--open-only] [--room UUID]... [--json]

List joined Agent Rooms for this session. Repeat --room for 1 to 16 rooms to list only those rooms. The answer must prove that scope; otherwise the command fails and does not fall back to the full list. Without --room it reads only the rooms that changed since the last list and takes the others from a private cache; if the server's room versions are incomplete, it reads every page. AB_ROOMS_LIST_INCREMENTAL=0 always reads every page and uses no cache.

artifactbridge rooms pending [--cursor TOKEN | --event-id UUID] [--runtime NAME] [--room UUID]... [--json]

Read one pending-target page for the selected workspace through artifactbridge_list_pending_room_targets. Repeat --room for 1 to 16 rooms to read pending targets in only those rooms. The answer must prove that scope; otherwise the command fails and does not fall back to unscoped results. This does not list memberships, acknowledge requests, or return every pending request. The JSON envelope contains schema_version, as_of, pending_targets, pending_recruits, next_cursor, and pass_complete. Rows preserve canonical Wake fields; older requests have wake: null. No task body or total is returned. Pass next_cursor unchanged to --cursor with the same runtime filter. An empty page can have a continuation. Repeat --event-id for 1 to 16 event UUIDs to refresh eligibility instead of reading the next page. It cannot be combined with --cursor. Each command makes one pending-tool call; it does not collect later pages. The desktop supervisor reads one page per workspace/filter poll and starts a fresh pass after pass_complete: true. A cursor is a seek hint, not an acknowledgment. Typed cursor_invalid discards only that hint, not safety state. JSON failures include error, exit_code, tool_code, and rpc_code; absent protocol codes are null. Invalid arguments exit 2; request and response errors exit 1. Only an initial structured unsupported command or tool response can select the older capped pending arrays. Authentication, permission, timeout, malformed-response, ordinary availability errors, and RPC -32602 do not authorize fallback. After modern discovery, loss of support pauses new in-scope submissions and preserves safety state instead of falling back. Older clients retain the newest-50 limitation. Eligibility refresh adds no permission or execution claim. It narrows stale-page exposure but leaves a read-to-launch race. Discovery does not promise replay, exactly-once execution, fixed latency, or recall of work already submitted. See the Rooms guide's pending-request compatibility section.

artifactbridge rooms leave --room REF [--participant ID] [--json]

Leave an existing Agent Room as all of your own participants: your agents and your answer-only participants. Your companion participant stays in the room. --participant takes a participant UUID and leaves only that own participant. --room takes a room UUID, a room key in any case (ABR-55), or a room URL. This changes presence only; room access stays unchanged. Rejoining gets a fresh participant ID. Closed rooms refuse the leave; never reopen a room to leave. Global --dry-run shows what would be left without contacting the server. --json prints the full MCP result.

artifactbridge rooms images list <room-ref> --json

List a Room's proven inline images that a person may make public, with opaque review IDs, revisions, status and active grants. Any member who can read the Room may list. No image, URL, token or public handle is returned.

artifactbridge rooms images revoke <room-ref> --input <JSON> --json

Revoke one exact public image grant. --input is exactly {"grantId","expectedLinkRevision","expectedGrantRevision","operationKey"} from list output. Room creator/owner or workspace owner/admin, or their agent, only. The link and original stay. A revoked image never returns; a person must approve it again.

artifactbridge rooms images operation <room-ref> <operation-key> --json

Read your own recorded result for one operation key. On an unknown revoke outcome, read this before any retry; never send a changed request with the same key. Preparing and approving a public image stay with a person in the web app's Share dialog.

artifactbridge rooms events --room ID --after-event-id ID [--json]

Read Agent Room events after one event ID. --room takes a room UUID, a room key in any case (ABR-55), or a room link.

artifactbridge rooms event --room ID --event-id ID [--json]

Read one Agent Room event by ID. The read cursor does not move. The desktop app sends the same read to its serve child as a room-event frame. --room takes a room UUID, a room key in any case (ABR-55), or a room link.

artifactbridge rooms watch [--room ID]... [--runtime NAME] [--event-types a,b] [--on-event CMD] [--once] [--json]

Watch Agent Room activity and run --on-event once for each new event. The command receives content-free AB_ROOM_ID, AB_EVENT_ID, AB_EVENT_TYPE, AB_TARGET_RUNTIME, and AB_WORKSPACE_ID variables. The command persists a per-room cursor. --once drains pending events and then exits.

artifactbridge rooms upload-image --room ID PATH... [--json]

Upload local PNG, JPEG, WebP, or GIF files (3 MiB or smaller each) to a joined Agent Room. Prints one Markdown image per file. Publish a message that contains the Markdown to show the images.

inbox

artifactbridge inbox [--json] [--verbose]

Show the needs-you feed for the connected workspace. --json emits schema-versioned metadata for the tray. --verbose adds text-only command deadlines and timings.

artifactbridge inbox --json --sync-consumer-id ID --sync-receipt

Show the needs-you feed with a feed receipt for one tray sync consumer. ID is the consumer UUID. The receipt holds your recipient stream position from before the feed read and is valid only for that consumer. After you store the complete feed, ack it with tray updates ack --cursor RECEIPT. Only your own human sign-in gets a receipt; an agent credential is refused. The read is never cached. A not-connected or offline state, such as a pending server update, prints its document without a receipt. It exits 1 when a connected answer has no receipt: a server without receipts.

artifactbridge inbox seen|unseen|dismiss KIND ID [--json]

Mark one of your own Inbox items as read or unread, or dismiss it. Other members see no change. KIND is the item kind, such as thread, proposal, or room_question; ID is the underlying item id. A dismissal answers, approves, or resolves nothing. It prints dismissed_activity_at; keep that exact stamp for undo. After a dismiss timeout, run inbox before you dismiss again.

artifactbridge inbox undo KIND ID --dismissed-activity-at STAMP [--json]

Remove your dismissal of that activity. "not restored" means that the stamp is stale or no dismissal exists.

docs

artifactbridge docs import PATH|- [--folder F | --no-folder] [--skill | --no-skill] [--visibility private|workspace] [--recursive [--select Q]] [--json]

Import one Markdown document or stage a recursive import plan for human review. A file whose name contains "skill" is registered as a skill by default; --no-skill turns that off. --visibility sets who can see a single imported document. Without it the server default applies. It is refused with --recursive or --repo.

artifactbridge docs import PATH --recursive --apply --plan PLAN_ID [--source-id SOURCE_ID] [--json]

Apply an approved local recursive import plan.

artifactbridge docs import --repo OWNER/NAME [--ref R] [--path SUB] [--json]

Stage a repository import plan for human review. --recursive is accepted and has no additional effect for repository import.

artifactbridge docs import --repo OWNER/NAME --apply --plan PLAN_ID [--ref R] [--path SUB] [--json]

Apply an approved repository import plan.

artifactbridge docs upload-image PATH (--folder F | --no-folder) [--title T] [--working] [--json]

Create a managed Library image from a local PNG, JPEG, WebP, or GIF file (3 MiB or smaller).

artifactbridge docs upload-image PATH --document ID --base-version V [--json]

Submit a local image as a new version of a Library image. A governed image waits for a human decision.

artifactbridge docs archive ID [--json]

Archive a document you can edit. It is hidden from the Library and search by default; it is not deleted. Archiving the source document of a workspace skill disables that skill. Nothing is written to a provider.

artifactbridge docs unarchive ID [--json]

Unarchive a document you can edit. A workspace skill sourced from it becomes active again.

artifactbridge docs duplicate ID [--json]

Copy a document you can read into a new governed managed document titled "Copy of <title>". You own the copy. It keeps the format (Markdown, CSV, TSV, or HTML), audience, visibility, and folder. Images are refused. Each call creates a new copy. After a timeout, find the copy with list or search before you run it again.

artifactbridge docs update ID --expected-version VERSION_ID --file PATH|- [--summary TEXT] [--json]

Write a full new body for a managed Markdown document. --file - reads standard input. --expected-version is the document_version_id you read. A stale version is refused with tool_code conflict and nothing is written. A working document gets a new version; a governed document gets a proposal that a human accepts or rejects. review_mode and outcome (updated, review_opened, or proposal_opened) say which path ran. --json adds content_hash, the SHA-256 of the body sent. --summary applies to a proposal.

artifactbridge docs subscription ID --mode watching|muted|default [--json]

Set your own notification preference for a document you can read. watching adds its blocking items to your Needs you; muted removes its ambient items and push notifications; default restores the workspace default.

companion

artifactbridge companion conversations list [--limit N] [--cursor C] [--json]

List your companion conversations, newest activity first. --cursor reads the next page.

artifactbridge companion conversations create [--title T] [--json]

Create a companion conversation. Each call creates a new one. After a timeout, list before you run it again.

artifactbridge companion conversations rename CONVERSATION_ID --title T [--json]

Rename one of your companion conversations. The last rename wins.

artifactbridge companion rooms list CONVERSATION_ID [--json]

List the Agent Rooms a conversation is in, with each binding's wake policy and policy revision.

artifactbridge companion rooms bind|unbind|move CONVERSATION_ID ROOM_ID [--json]

Put a conversation in an Agent Room, take it out, or move the room from another of your conversations. A new or moved binding starts with wake policy off. Binding a room does not join it.

artifactbridge companion rooms policy BINDING_ID --policy off|ask --expected-policy-revision N [--confirm-wake] [--json]

Set when room activity can wake the conversation. Ask needs --confirm-wake on every call. Use --confirm-wake only when your human chose that policy. A stale revision is a conflict: list again. Automatic is human-only: your human turns it on in the ArtifactBridge web app.

artifactbridge companion tools get CONVERSATION_ID [--json]

Show a conversation's tool picks: the groups turned off and the tools that ask each time.

artifactbridge companion tools set CONVERSATION_ID [--disabled-group G]... [--ask-tool T]... [--json]

Replace a conversation's tool picks. Omitted lists are empty. Picks never show a tool the workspace hides.

profile

artifactbridge profile get [--json]

Read your own profile: display name, photo, revision, and the avatar color in the selected workspace. Your name and photo show in every workspace. Names are framed as untrusted text.

artifactbridge profile set-name --name TEXT|--clear --expected-revision N [--json]

Set your display name (64 characters or fewer), or clear it to show the Google or email name again. A stale revision is refused with the current profile. No change is retried: read the profile before you try again.

artifactbridge profile photo upload PATH --expected-revision N [--json]

Upload a local PNG, JPEG, or WebP file (3 MiB or smaller) as your photo. The file is encoded locally. Prints an Undo token once. Keep it out of files and logs.

artifactbridge profile photo remove --expected-revision N [--json]

Remove your photo. Initials show instead. Prints an Undo token once.

artifactbridge profile photo undo --undo-token-stdin --expected-revision N [--json]

Undo the last photo change. Reads the Undo token from stdin, never from arguments. Undo expires after about two minutes.

artifactbridge profile avatar-color set COLOR [--json]

Set your avatar color in the selected workspace only: red, orange, yellow, green, teal, blue, violet, or pink.

preferences

artifactbridge preferences get [--json]

Read your own theme and coach marks. Replay and notification consent are not shown.

artifactbridge preferences theme set dark|light [--json]

Set your theme.

artifactbridge preferences coach-mark seen MARK [--json]

Mark one coach mark as seen: library, documents-and-skills, or changes. It cannot be reset.

agents

artifactbridge agents list [--agent-id UUID] [--limit N] [--cursor CURSOR] [--setup-options] [--space-limit N] [--space-cursor CURSOR] [--json]

Read one page of agents you can see in the selected workspace. A next-page cursor is printed when more rows exist. --setup-options adds one page of Spaces you can choose and the harness options. --limit and --space-limit are 1 to 100. --agent-id reads one agent and cannot be combined with --cursor. --json prints the server envelope unchanged.

artifactbridge agents create --name NAME --space UUID [--description TEXT] [--harness ID] [--idempotency-key UUID] [--json]

Create an agent that works in one fixed Space. Only you can use it. A human sign-in is required. The command saves a private local record of the request before it sends it. Without --idempotency-key it makes a new key. When the outcome is unknown, the command prints the key and the recovery command. Do not create the agent again with a new key.

artifactbridge agents create --recover UUID [--json]

Send the saved create request with this key once more, for the same account and workspace, within 24 hours of the first send. A lost, expired, or uncertain request stops. A list cannot prove that a create failed: create again only after the person approves a new create.

artifactbridge agents update UUID [--name NAME] [--description TEXT] [--space UUID] [--harness ID|--clear-harness] [--json]

Change the configuration of an agent you own. Only the given fields change. --description "" clears the description. --clear-harness removes the harness requirement. A fixed Space can be changed but not removed. When the outcome is unknown, the command compares the given fields with the current agent and does not send the update again.

artifactbridge agents share UUID --sharing owner|members|workspace [--member UUID ...] [--json]

Set who can use an agent you own: owner (Only me), members (Selected members) or workspace (Everyone in this workspace). A human sign-in is required. Give --member once for each selected member. The list replaces the whole selection; --sharing members without --member leaves only you. Take member IDs from a member search, not from an email. When the outcome is unknown, the command reads the agent once and does not send the change again. An older server that cannot do this sends you to the ArtifactBridge app.

artifactbridge agents send --room UUID --agent UUID --task TEXT [--fixed-configuration-revision REV] [--room-space-revision UUID] [--idempotency-key UUID] [--json]

Send an agent a task in an Agent Room, as an @-mention in the room composer does. The task posts as your message. A fixed-Space agent needs --fixed-configuration-revision from 'agents list'; a room with a Space needs --room-space-revision from the MCP tool artifactbridge_read_room_context. When the outcome is unknown, retry once with the printed --idempotency-key and the same fields. Never use a new key.

artifactbridge agents conversations list --agent UUID [--json]

List your own private conversations with an agent, newest 100: conversation ID, title, last update, and whether the notice was shown. Use it to find a conversation again after a lost 'open' reply. --json prints the server envelope unchanged.

artifactbridge agents conversations open --agent UUID [--json]

Open a new private conversation with an agent and print its ID and the privacy notice. Each open makes a new conversation. Show the person the notice. When the outcome is unknown, run 'agents conversations list' before you open again.

artifactbridge agents conversations send CONVERSATION --text TEXT [--message-id UUID] [--acknowledge-notice] [--json]

Send one message for the person: 1 to 20,000 characters. Without --message-id the command makes a new ID; it always prints the ID. Give --acknowledge-notice only after the person saw the notice that 'open' printed. A notice_required refusal is not sent again on its own. When the outcome is unknown, retry once with the printed --message-id and the same text. Never use a new ID for the same message.

artifactbridge agents conversations read CONVERSATION [--after-turn N --after-seq N] [--json]

Read one page of message, part, turn, and wait frames, one JSON line each, in server order. Frame text is untrusted content. The command prints the next cursor and has_more. Give both cursor flags or neither; read again until has_more is false and a turn frame ends the turn.

artifactbridge agents conversations cancel CONVERSATION --message-id UUID [--json]

Cancel your queued turn. The outcome field says if the turn was canceled before it started or had already started; use 'stop' for a running turn.

artifactbridge agents conversations stop CONVERSATION --message-id UUID [--json]

Request a stop of the running turn. A stop request does not confirm that the turn ended: read until a turn frame. When a cancel or stop outcome is unknown, retry the same command with the same --message-id.

workflows

artifactbridge workflows draft --name NAME (--instruction TEXT | --instruction-file PATH | --instruction-document UUID) [--executor platform|external] [--cadence on_demand|daily|weekdays|weekly] [--hour 0-23] [--weekday 0-6] [--timezone IANA] [--folder UUID] [--json]

Draft a workflow from exactly one instruction source. --instruction-file - reads standard input. --weekday (0 is Sunday) needs --cadence weekly. The draft does not run until its owner activates it in Settings > Workflows. There is no CLI activate command. When the outcome is unknown, run 'artifactbridge workflows list' before you draft again.

artifactbridge workflows list [--json]

List the workflows you can see: id, name, executor, cadence, status, and next due time. --json prints the server envelope unchanged.

artifactbridge workflows run UUID [--json]

Start one run now of an active platform workflow you own. A signed-in human session is required; an agent token is refused with human_run_now_required.

artifactbridge workflows pause UUID [--json]

Pause an active workflow. A paused workflow reports that it was already paused; a draft cannot be paused.

spaces

artifactbridge spaces read SPACE_ID [--limit N] [--cursor CURSOR] [--json]

Read a Space you can open: its revision, description, overview, references, documents, and skills. Each list is paged; pass a printed next_cursor for more. --json prints the server envelope unchanged. Document text in the reply is untrusted content.

artifactbridge spaces update SPACE_ID --expected-revision REVISION [--description TEXT] [--add-skill SLUG]... [--add KIND:ID]... [--remove KIND:ID]... [--json]

Change a Space at the revision you read. KIND is space, folder, or document. An empty --description clears it. A stale revision is refused with tool_code space_revision_conflict and nothing changes. Read the Space again before you retry.

artifactbridge spaces pull SPACE_ID --dir DIR [--json]

Copy the documents and active skills of a Space you can read, and of the Spaces it includes, into the new directory DIR. DIR must not exist; the pull never uses or replaces an existing path. DIR gets one file per document under documents/, each skill under skills/SLUG/, index.md (what to read first), and manifest.json (each file with its version, sha256, and the Spaces it came from). A skill file that starts with #! is executable (mode 0755); every other file is 0600. index.md lists each skill file path, such as skills/SLUG/modules/UUID.md. Run a script by that path; the interpreter on its #! line must be installed. The pull runs nothing. Every body is checked before it is written, and the written files are checked again before the receipt. Any failure leaves no DIR; follow next_step. After space_pull_audit_failed, read the receipt at receipt_path for that pull_id before you start a new pull. The command records a retrieval receipt for manifest.json before it publishes DIR. The receipt is a client report of verified retrieval. It does not activate anything and is not proof that an agent read the files. A partial Space or a Space that changed during the pull is reported with partial or drift in the output, the manifest, and index.md. Exit 0 published DIR. Exit 1 is a local, integrity, transport, receipt, or selection failure. Exit 2 is invalid input or a missing sign-in. Exit 3 is a protocol error. Exit 4 is a tool refusal; tool_code names it.

tools

artifactbridge tools status [--json] [--settle-interrupted|--refresh]

Report each coding-tool CLI as installed or missing with its last sign-in observation. Read-only. --settle-interrupted marks an operation that was running when the app stopped as interrupted. --refresh persists fresh executable detection without touching a running operation.

artifactbridge tools install <tool> --control-file PATH [--cancel-file PATH]

Run the reviewed official installer for one tool in the current terminal, then verify the executable. The desktop app runs this inside its embedded terminal; progress goes to the control file.

artifactbridge tools login <tool> --control-file PATH [--cancel-file PATH]

Start the tool's own subscription sign-in, then re-check its status from a fresh process.

artifactbridge tools auth-status <tool> [--json]

Run the documented non-interactive sign-in check for one tool. A tool without one reports unknown.

artifactbridge tools report [--json]

Publish the newest content-free tool observations for this device to the connected workspace.

setup

artifactbridge setup status [--json]

Show authentication, exposure, migration, completion, and one row per coding tool.

artifactbridge setup plan --clients LIST|none [--json]

Preview the setup transaction for the complete desired coding-tool set. Read-only.

artifactbridge setup apply --clients LIST|none [--plan ID] [--accept-owner-migration] [--json]

Reconcile the machine to the desired coding-tool set in one transaction. Removal touches only ArtifactBridge-owned content. --plan rejects a stale plan.

uninstall

artifactbridge uninstall [--dry-run] [--purge] [--previous-owner]

Remove owned files and configuration. An edited ArtifactBridge skill or workspace picker is backed up to skills/backups in the state folder first; files that you added stay. --purge also removes user state. --purge removes Skill Hub skills too. An edited skill is backed up to ~/ArtifactBridge skill backups first; files that you added stay.

artifactbridge uninstall --app --json

Remove the application: owned cleanup first, then the per-owner OS removal.

version

artifactbridge version

Print the bridge version.

help

artifactbridge help

Show the main help or help for one topic.

agent

artifactbridge agent room

Keep hooks synchronized with the active Agent Room lifecycle.

artifactbridge agent runtime

Choose the agent CLIs this machine may wake.

artifactbridge agent wake

Control when this machine may wake an agent for one workspace or Agent Room.

artifactbridge agent presence

Publish this machine's live-presence pointers for its joined Agent Rooms.

artifactbridge agent hooks

Report the harness hooks that record room-to-session bindings.

artifactbridge agent telemetry

Keep agent status available to the tray while agents run.

artifactbridge agent accounts

Show, allow, or revoke the coding-tool accounts that agents may use.

artifactbridge agent connections

Show, authorize, grant, revoke, or enable the GitHub repository connections that agents may use.

artifactbridge agent room remember --room-id ID --participant-id ID --runtime NAME

Keep Agent Room lifecycle state for hook execution.

artifactbridge agent room mark-read [--cursor C]

Keep Agent Room read state for hook execution.

artifactbridge agent room mark-update --kind KIND

Keep Agent Room update state for hook execution.

artifactbridge agent room gate [--json] [--require-active|--require-update|--require-final]

Check Agent Room lifecycle requirements for hook execution.

artifactbridge agent runtime list [--json]

Show the agent command-line interfaces that this machine may wake.

artifactbridge agent runtime discover [--json]

List supported executables from PATH and show their registry state.

artifactbridge agent runtime enable <runtime> --working-directory PATH [options]

Allow this machine to wake one agent command-line interface. --wake-routing dedicated starts the registered command for every wake of the runtime, one at a time, instead of the chat bound to the Room. --wake-routing bound restores the default. With bound routing, a Hermes wake that its chat cannot take runs once in the registered command, but only when you set that command with --command. Run the command again with --command and --working-directory once after an update, also when the command is already saved. Other runtimes keep their bound behavior.

artifactbridge agent runtime disable <runtime> [--json]

Prevent this machine from waking one agent command-line interface. Built-in runtimes are enabled by default. Disable stops new starts.

artifactbridge agent runtime default <runtime>|--clear [--json]

Set the enabled runtime that a new wake session starts when no Room binding chooses one, or clear it.

artifactbridge agent wake get --workspace ID [--room ID] [--json]

Read the agent wake policy for one workspace or room.

artifactbridge agent wake set <auto|ask|off> --workspace ID [options]

Set the agent wake policy for one workspace or room. A limit outside its allowed range is stored at the nearest allowed value, and the command prints a warning.

artifactbridge agent wake reset --workspace ID [--json]

Request a restart of the consecutive automatic-wake count for one workspace. The command saves the request and returns its generation; the tray applies it once, before its next wake. The limits do not change, and the other wake limits still apply. The CLI and the tray must come from the same release.

artifactbridge agent wake report --room ID --event ID (--participant ID | --runtime LABEL) --state STATE [--detail TEXT] [--json]

Deliver one wake receipt to the server. Name a caller-owned participant, or name a runtime when no participant row exists.

artifactbridge agent wake runs [--room ID] [--event ID] [--counts] [--json]

Read the active environment and workspace wake audit. --counts reports only protected ordinary and dedicated replay disk slots, without raw rows. Counts are exact, including retained rows above the admission capacity of 256 per pool. Wire counts and sampled maxima are nonnegative integers up to 9007199254740991. Counts exclude transient in-memory reservations; --counts cannot be used with --room or --event.

artifactbridge agent presence publish [--json]

Publish this machine's live-presence pointers for its joined Agent Rooms.

artifactbridge agent hooks install [--json]

Install the Claude Code and Codex hooks for wake session capture. Eligible commands repair a missing hook already. This one reports it.

artifactbridge agent hooks install --hermes-profile NAME [--enable-wake] [--json]

Add the Hermes capture hook and the wake plugin to one Hermes profile. With --enable-wake it also enables the plugin and sets its injection grant; you still approve the hook and restart Hermes.

artifactbridge agent hooks status --hermes [--hermes-profile NAME] [--json]

Report whether room wakes can reach a chat of the Hermes profile that setup configures, and the next step. Writes nothing.

artifactbridge agent hook-event --runtime NAME

Record one harness hook payload from standard input.

artifactbridge agent wake-wait --runtime NAME

Wait for a room wake handed to this session and exit 2 with its prompt. Claude Code runs it as an asyncRewake hook; the sitting session takes the wake.

artifactbridge agent telemetry relay [--once]

Keep local agent status available to the tray supervisor. This command is not a resident daemon.

artifactbridge agent telemetry repair

Restore the tray supervisor's owned agent-status files.

artifactbridge agent accounts list [--json]

List the allowed coding-tool accounts and the account signed in to each tool. A person must run this command. An agent cannot. --json has a stable shape for the tray app.

artifactbridge agent accounts allow --client <runtime> [--workspace <selector>] [--json]

Allow the account that is signed in to one coding tool for one workspace. A person must run this command in their own terminal. An agent cannot, not even for its own tool. A session that the app started without a person cannot.

artifactbridge agent accounts revoke <approval-id> [--json]

Revoke one allowed account. A person must run this command. An agent cannot.

artifactbridge agent connections list [--workspace <selector>] [--json]

List the workspace's repository connections and the agents granted each one. A workspace owner or admin must run this command. An agent cannot.

artifactbridge agent connections authorize --installation <id> --repository-id <id> --name <owner/repo> [--workspace <selector>] [--json]

Record one GitHub repository for the workspace. The connection starts disabled, with no agents. The installation must be the workspace's GitHub App installation. The repository id is the key; the name is for display only.

artifactbridge agent connections grant <connection-id> --installation <id> --repository-id <id> --agent <agent-id> [--workspace <selector>] [--json]

Let one workspace agent use one repository connection.

artifactbridge agent connections revoke <connection-id> --installation <id> --repository-id <id> [--agent <agent-id>] [--workspace <selector>] [--json]

With --agent, remove that agent's grant. Without it, revoke the connection and all of its grants.

artifactbridge agent connections enable <connection-id> --installation <id> --repository-id <id> --revision <n> --operation <operation>... [--workspace <selector>] [--json]

Enable the connection at its current revision with the named operations: contents_read, contents_write, pull_requests_read, pull_requests_write. The operations replace the previous set. A workspace owner or admin must run this command. An agent cannot.