CLI reference

Getting started

(no command)

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

login [--staging | --server URL] [--workspace W] [--install-clients LIST]

Start browser OAuth for one environment session.

login [--staging | --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.

rooms list|watch|events

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

docs import PATH|- [--folder F | --no-folder] [--skill | --no-skill] [--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.

workspace list|use|clear

List or select the workspace for this environment.

skills list|install|uninstall|sync

Manage workspace skills for supported agent clients.

skills changes list|show|send|discard

skills reviewer 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.

update status [--json]

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

update auto on|off

Manage verified automatic toolkit updates.

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

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, 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.

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.

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.

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.

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 show <id> [--json]

Show one staged skill change against the workspace 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. An owner decides in the Inbox. The digest comes from 'show'. A change or a workspace version that moved since is refused.

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

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

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 install <slug> [--clients claude,codex,grok,opencode,hermes,openclaw] [--json]

Install a workspace skill for the selected clients. A client whose coding tool is not on this machine is refused (tool_not_detected) and nothing is written.

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

Re-run a failed install.

artifactbridge skills update [<slug>]

Re-pin installed skills whose content changed or that carry a pending hub Update intent.

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

Remove exactly what install wrote.

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.

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 [--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. --once exits 0 after the first signal. The output is always NDJSON. --json is the explicit form.

telemetry

artifactbridge telemetry enable [--clients claude,codex,grok]

Enable the tray-supervised status-only local relay.

artifactbridge telemetry disable

Stop local collection and revoke relay access.

artifactbridge telemetry status [--json]

Show relay health, queue, upload, and drop metadata.

artifactbridge telemetry remove

Stop collection and remove only owned relay state.

rooms

artifactbridge rooms status [--json]

Show local Agent Room lifecycle state.

artifactbridge rooms list [--runtime NAME] [--json]

List joined Agent Rooms for this session.

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

Read Agent Room events after one event ID.

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.

docs

artifactbridge docs import PATH|- [--folder F | --no-folder] [--skill | --no-skill] [--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.

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.

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. --purge also removes user state.

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 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.

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 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.

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] [--json]

Read the active environment and workspace wake audit.

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 [--json]

Add the Hermes capture hook and the wake plugin to one Hermes profile. You approve the hook and enable the plugin in Hermes yourself.

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.