Docs
Reference

CLI reference

Every arcon command and flag. arcon --help and arcon <command> --help print the same on your computer; arcon -v prints the version.

7 min read

Setup and pairing

arcon pair [--no-qr]

Pair this computer with your account: shows a QR code and a 6-character code (valid 10 minutes, once), waits while you scan it and confirm the computer’s details on your phone, and saves the pairing to ~/.arcon/credentials.json. If you tap This isn’t my computer, it stops with “Pairing was declined on the phone.”

--no-qr: Print only the code, no QR

arcon status [--json] [--session <id>]

Pairing, daemon, hooks, skill, Codex and phone status (undelivered phone messages, sessions waiting for you). Exit code 0 means paired and running.

--json: Machine-readable output (includes session_id for the current folder)
--session <id>: Session to report on (default: the one for the current folder)

arcon logout

Forget the pairing on this computer (and mark it offline when reachable).

arcon update [--check] [--no-restart] [--force] [--json]

Update Arcon to the latest version. Like the installer, it checks the release’s signature before installing, then restarts a running daemon.

--check: Only check whether an update is available
--no-restart: Don’t restart the daemon after updating
--force: Reinstall even if already up to date
--json: Machine-readable output

The daemon

arcon start [--detach | --foreground] [--port N] [--no-codex] [--phone-wait s] [--ask-timeout s]

Run Arcon: the background process that talks to your account, receives hook events and watches Codex. From a terminal it starts in the background and tells you where the logs are, so closing the window doesn’t stop it (connector 0.12.1 and later). Use --foreground to keep it attached.

-d, --detach: Run in the background and return (waits up to 15 s for it to come up). The default in a terminal
--foreground: Stay attached to this terminal, for debugging. Closing the terminal doesn’t stop it
-p, --port <port>: Local port (default 47831)
--no-codex: Don’t watch Codex sessions
--phone-wait <seconds>: Take over: how long a finished turn waits for your next phone message (default 1200, max 1750)
--ask-timeout <seconds>: How long questions wait for an answer (default 600, max 880)

arcon stop [--port N]

Stop a background daemon.

-p, --port <port>: Local port

Installs

arcon install claude-code [--uninstall] [--no-skill] [--command <cmd>] [--settings <path>]

Add Arcon’s hooks to Claude Code’s settings (idempotent, keeps a timestamped backup) and install the skill. Restart open Claude Code sessions afterwards.

--uninstall: Remove Arcon’s hooks (and the skill unless --no-skill)
--no-skill: Don’t touch the Arcon skill or ~/.codex/AGENTS.md
--command <cmd>: Hook command prefix (default: arcon hook), e.g. an absolute path to arcon.cmd
--settings <path>: settings.json to edit (default: ~/.claude/settings.json)

arcon install codex [--uninstall] [--no-hooks] [--dir <path>]

Connect Codex: hooks in ~/.codex/hooks.json (approvals on your phone, boundaries before tools run) and the session watcher for ~/.codex/sessions. Then trust the hooks once in Codex: /hooks, press t.

--uninstall: Remove Arcon’s Codex hooks and stop watching Codex sessions
--no-hooks: Only watch sessions (no approvals on the phone, boundaries after the fact)
--dir <path>: A custom sessions folder

arcon install skill [--uninstall]

Install the Arcon skill for Claude Code (~/.claude/skills/arcon) and an Arcon section in ~/.codex/AGENTS.md.

--uninstall: Remove both

arcon install cli [--no-restart]

Copy the self-contained CLI to ~/.arcon/app and point ~/.local/bin/arcon at it (fast start-up under WSL). The one-line installer already does this; not needed on Windows.

--no-restart: Don’t restart a running daemon

arcon install shell [--uninstall] [--powershell] [--min-seconds N]

Report long-running commands from any bash or zsh terminal as Terminal sessions (a marked block in ~/.bashrc / ~/.zshrc).

--uninstall: Remove the block
--powershell: Print a PowerShell profile snippet instead (profiles are never edited)
--min-seconds <n>: Report commands running at least this long (default 10)

Diagnostics and support

arcon doctor [--json] [--fix <id>] [--fix-safe]

Check everything between this computer and your phone, in plain English. Exit code 1 when something failed.

--json: The full report, machine-readable
--fix <id>: Apply one fix (ids are shown in the report)
--fix-safe: Apply every safe, automatic fix

arcon logs [-n N]

The end of Arcon’s log, with secrets redacted.

-n, --lines <n>: How many lines (default 60, max 500)

arcon support ["first message"] [--agent claude|codex] [--model <id>] [--new]

Open an Arcon Support chat from the terminal, e.g. arcon support "my phone doesn’t update". The support agent itself uses arcon support propose, escalate and bundle (with --subject, --summary, --session).

--agent <claude|codex>: Which of your agents answers (default: Claude Code if installed)
--model <id>: Model for the support agent (default: a fast one)
--new: Start a new Help chat instead of continuing today’s
--json: Machine-readable output

Tools

arcon tools [list|catalog|add <id>|remove <name>] [--runtime claude-code|codex]

Your agents’ tools (MCP servers) on this computer: list them, browse the catalog, add or remove one. The same list is under Tools in the apps.

--runtime <claude-code|codex>: Which agent (default: claude-code)
--name <name>: add: a name for a custom server
--url <url>: add: the https address of a custom server
--transport <http|sse>: add: transport of a custom server (default http)
--json: Machine-readable output

Run any command

arcon run [--title T] [--cwd dir] -- <cmd> [args…]

Run a command and stream its output to your phone as a session. The exit code decides completed or failed; Stop from the app ends it. Everything after -- is passed through untouched.

-t, --title <title>: Session title (default: the command)
-C, --cwd <dir>: Working directory

arcon hook <Event>

The entry point Claude Code’s hooks call (reads JSON on stdin). You never run it yourself; it never breaks your Claude Code session.

Git

Git for a session’s repository, the same actions the apps offer (Git from your phone). Nothing is ever force-pushed.

diff [path] [--staged]: What changed; --staged for only what is staged
commit [paths…] -m <text> | --ai: Commit with your message, or let the fast model write one
push [--confirm-base]: Push; pushing the base branch (main/master) needs --confirm-base
pr [create|refresh|ci-fix]: Open a pull request (--title, --body, --draft, --base), refresh its checks, or ask the agent to fix failing CI
checkpoint [label] · restore <id>: Save a private snapshot on this computer, or go back to one
worktree merge|pr|discard: Finish an isolated worktree; discard needs --confirm
--session <id|latest> · --json: Which session’s repo; machine-readable output

Agent commands

What the Arcon skill uses. All of them talk to the local daemon and are silent no-ops (exit 0) when it isn’t running. Each takes --session.

arcon report --task "…" [--progress 0..1]

Set the session’s status line and progress.

--task <text>: What the agent is doing now (60 characters reads best)
--progress <0..1>: Explicit progress; omit to derive it from the checklist
--session <id|latest>: Which session (default: $ARCON_SESSION_ID, then the session of the current folder, then the most recent one)

arcon step "<title>" --state todo|doing|done|failed [--position n]

Create or update one checklist item (unique by title within the session).

--state <state>: todo, doing, done or failed (required)
--position <n>: Order in the checklist
--session <id|latest>: Which session (default: $ARCON_SESSION_ID, then the session of the current folder, then the most recent one)

arcon say "…"

A one-line message to you in the chat; @Name mentions a teammate agent.

--session <id|latest>: Which session (default: $ARCON_SESSION_ID, then the session of the current folder, then the most recent one)

arcon log "…" [--level info|warn|error]

Add a line to the session’s live output.

--level <level>: info (default), warn or error
--session <id|latest>: Which session (default: $ARCON_SESSION_ID, then the session of the current folder, then the most recent one)

Publish a file (up to 25 MB) as a document. Markdown renders natively; publishing the same title again replaces it.

--title <title>: Document title (default: file name)
--kind <kind>: Default: from the extension
--session <id|latest>: Which session (default: $ARCON_SESSION_ID, then the session of the current folder, then the most recent one)

arcon ask "…" [--options a,b,c] [--default a] [--multi] [--timeout 600]

Ask you on your phone and wait. Prints the answer (exit 0); on timeout prints the default (exit 0) or nothing (exit 2).

--options <a,b,c>: Comma-separated choices
--default <option>: Printed when nobody answers in time
--multi: Several options may be chosen
--timeout <seconds>: How long to wait (default 600)
--session <id|latest>: Which session (default: $ARCON_SESSION_ID, then the session of the current folder, then the most recent one)

arcon phone on|off

Take over on or off: with it on, Claude Code waits for your phone at the end of each turn instead of stopping.

--session <id|latest>: Which session (default: $ARCON_SESSION_ID, then the session of the current folder, then the most recent one)

Files and environment

File	What’s in it
`~/.arcon/credentials.json`	The pairing (written by arcon pair, readable only by you)
`~/.arcon/config.json`	port, phone_wait_s, ask_timeout_s, codex settings, stale_after_min
`~/.arcon/daemon.log`	The log (JSON lines)
`~/.arcon/app`	The installed program; ~/.local/bin/arcon runs it

Variable	Effect
`ARCON_HOME`	Use another state folder instead of ~/.arcon
`ARCON_DAEMON_PORT`	The daemon port hooks and commands talk to
`ARCON_SESSION_ID`	Force the session for agent commands
`ARCON_QUIET=1`	Silence the CLI’s own notes on stderr
`ARCON_DEBUG=1`	Hook and CLI diagnostics on stderr
`ARCON_LOG_LEVEL`	Daemon log level (e.g. debug)
`CLAUDE_HOME · CODEX_HOME`	Where Claude Code and Codex keep their files
`HTTPS_PROXY`	Behind a corporate proxy (with NODE_USE_ENV_PROXY=1 on Node 24+)