ARC CLI — Command Reference

ARC CLI is the command-line tool for interacting with Arc Cloud. Manage projects, issues, wiki, and skills straight from your terminal.

• Source code: clients/arc-cli.ts
• API client: clients/lib/api.ts
• Build: scripts/build-arc.sh (compiled binary)

Installation and Setup

Configuration is stored in ~/.arc/config.json (server_url, token, connected_at).

arc login [server_url]

Authorization via device code flow. Opens a browser for confirmation.

arc login                          # default server: https://arc-os.co
arc login https://my-server.com    # custom server

After launch the CLI prints a URL and a one-time code. Open the URL in a browser, confirm the authorization — the CLI receives the token automatically.

arc login --token <token>

Direct token authorization (for automation or when device flow is unavailable).

arc login --token eyJhbGciOiJIUzI1NiI...

The CLI validates the token against the API before saving it.

arc logout

Removes credentials from ~/.arc/config.json and strips the ARC block from CLAUDE.md (if present).

arc logout

arc projects

List the projects available on the server.

arc projects

Output:

Available projects:

  Name                   Type           Status
  --------------------------------------------------
  arc-v2                 bot            running
  my-project             bot            unknown

Starting a Session

arc <project> [mode]

Initializes a Claude session with full project context. Equivalent to arc start <project> [mode].

arc my-project dev             # dev mode (default)
arc my-project prod            # prod mode
arc --role clceo my-project    # with the CEO role

What happens on launch:

1. Request GET /api/cli/init/:project/:mode — fetches CLAUDE.md, worker config, skills
2. Session-start picker (issue #115) — interactive selection of the active issue for the session: open issues (sorted P0→P3 + recent-first, fuzzy filter if >10), recently-closed (with reopen-confirm on pick), [n] create new, [q] skip with double-confirm. The selected id is stored in ~/.arc/sessions/<project>-<worker>.json as active_issue_id
3. Context injection into the local CLAUDE.md (ARC Cloud block + Active issue: #N — Title block)
4. The ARC_ACTIVE_ISSUE_ID=<id> env var is passed to the Claude subprocess — the Bash tool sees it for arc issue log without re-prompting
5. Cleanup of deprecated .mcp.json entries (if any)
6. Launch of the claude subprocess with TTY interactivity
7. Start of the background watcher (see "Session Monitoring")

Parameters:

Non-interactive bypass: ARC_ISSUE_ID=42 arc my-project dev skips the picker and uses the given id (for CI/scripts).

Mid-session switch: arc issue switch <id> (from a parallel terminal) switches the active issue — it writes switched_away on the previous issue + switched_in on the new one. The current session picks up the new id after a restart.

arc continue <project> [mode]

Resume the last Claude Code session (24-hour window). Auto-restores active_issue_id without re-prompting.

arc continue my-project             # pick up the previous session + active issue
arc continue my-project --reselect-issue   # force re-run picker

arc tour

Interactive 5-step onboarding in the terminal (mirrors web checklist). Progress syncs with the web dashboard.

arc tour

Issue Management

arc issues [--status <filter>]

List the project's issues.

arc issues                    # open only (default)
arc issues --status closed    # closed only
arc issues --status all       # all issues

Output:

3 issue(s):
- #12 [P1] Add dark mode [ux, frontend]
- #15 [P2] Fix login timeout
- #18 [P0] Critical: DB migration

arc issue create --title "..." [options]

Create a new issue.

arc issue create --title "Add dark mode" --priority P1 --labels "ux,frontend"
arc issue create --title "Fix bug" --body "Detailed description here" --priority P0

Parameters:

arc issue update <id> [options]

Update an existing issue.

arc issue update 12 --status closed
arc issue update 15 --priority P0 --title "Critical: Fix login timeout"
arc issue update 18 --body "Updated description with more context"

Parameters:

At least one parameter is required for an update.

arc issue log <id> "<text>" [--author <name>]

Add a progress entry to an issue (activity log).

arc issue log 12 "Started implementation"
arc issue log 12 "Dark mode toggle works" --author "developer"

Parameters:

The backend (POST /api/mcp/issues/:project/:id/log) accepts optional fields type (whitelist: log / session_start / session_end / switched_in / switched_away / auto_summary / reopened) and ts (ISO-8601 for backdated entries; future-dated values are clamped to now). Used internally by the session-start picker (#115) and arc retro (#117).

arc issue switch <id>

Switch the active issue for the current session (issue #115). Saves to ~/.arc/sessions/<project>-<worker>.json, writes switched_away on the previous issue + switched_in on the new one.

arc issue switch 42
arc issue switch 42 --worker consultant   # for a specific worker (default: developer)

Validation: the issue must exist and be open. If it is closed — run arc issue update <id> --status open first.

arc sessions <project> [mode]

View all saved sessions for a project and resume any of them on demand — even if you forgot to run continue (issue #131).

arc sessions arc-v2                    # all workers
arc sessions arc-v2 --worker developer # developer only

Prints a table: transcript status (● present / ✗ lost), worker name, short session-id, session age, active issue. Below it — a list of all .jsonl files, including "orphaned" ones (not bound to the current worker).

After the table — an interactive picker:

• Enter a worker name (developer, sentinel…) — resumes that worker's latest session
• Enter the 8 characters of a session-id — resumes that specific session
• Enter — skip

How it works: the picker writes the chosen session_id + transcript_path to ~/.arc/sessions/<project>-<worker>.json, then launches a regular arc <project> continue.

arc retro <project> [options]

Reconstruct issues retroactively from session history + git log (issue #117). Scans ~/.arc/sessions/<project>-*.json, reads the first user prompt from the transcript JSONL, collects commits via git log --since=started_at --until=ended_at.

arc retro gapap                       # dry-run — prints the plan
arc retro gapap --apply               # creates issues
arc retro gapap --since 2026-01-01    # only after this date
arc retro gapap --worker consultant   # only for one worker

What is skipped automatically:

What happens on --apply:

1. createIssue for each candidate (priority=P2, label=retro)
2. Backdated activity entries: session_start (started_at) + auto_summary per commit (commit timestamp) + session_end (ended_at) — via POST /log with the ts field
3. Sessions >30 days old with commits → status=closed immediately. Recent unfinished → status=open.

Skills and Knowledge

arc skill <name>

Load a skill from Cloud. Prints the skill's instructions and evals (if any).

arc skill consultant_system
arc skill crm-api-reference

Requires the ARC_PROJECT variable (set automatically by arc start).

If the skill is not found, the CLI prints the list of available ones.

arc kb search "<query>"

Search the project wiki. Keyword match on file names; returns up to 5 best results (content truncated to 2000 characters).

arc kb search "deployment"
arc kb search "arc-cli"

arc learnings

Accumulated rules and corrections from all of the project's sessions.

arc learnings

Output:

- [cli] Always validate project name before API calls
- [deploy] Test nginx config before reload

Wiki and Roadmap

arc wiki update --file <name> --content "..."

Create or update a project wiki page.

arc wiki update --file "architecture" --content "# Architecture\n\nMain components..."
arc wiki update --file "deploy-guide" --content "$(cat my-doc.md)"

Parameters:

Output: Wiki created: architecture.md (342 bytes) or Wiki updated: ...

arc roadmap sync --phase <id> --status <text> [--notes "..."]

Update a phase status in the project roadmap.

arc roadmap sync --phase 45 --status "IN PROGRESS"
arc roadmap sync --phase 44 --status "DONE" --notes "All analytics redesigned"

Parameters:

Reporting

arc report --summary "..." [options]

Send a session report to Arc Cloud.

arc report --summary "Implemented dark mode with system preference detection"
arc report --summary "Fixed auth bug" --files "auth.ts,middleware.ts" --decisions "Switched to HMAC tokens"

Parameters:

Documentation Enforcement (Phase 49.1-49.2.1)

ARC has a built-in system that keeps documentation up to date without human reminders. It works together with the pre-push git hook (scripts/check-docs-coverage.ts).

arc wrapup

Read-only checklist — shows which docs need updating for unpushed commits.

arc wrapup

Delegates to scripts/check-docs-coverage.ts. Mapping:

arc wrapup --generate

Auto-draft skeleton entries for missing docs. Writes TODO-marked stubs to:

• learnings.md — timestamp + auto-detected scope (api/backend/frontend/infra/process)
• docs/ROADMAP.md — Phase NN heading + commit summary
• docs/status/current-state.json — version bump + prepended change

arc wrapup --generate
# then: review via `git diff`, replace TODOs with real content, commit

TODO markers intentionally won't pass review — the structure is generated, not the content.

arc wrapup --from-summary "<text>"

Capture a research/decision/finding directly into learnings.md without a code commit. Closes the blind spot for work without code commits (capacity analysis, broker comparison, trade-off review).

arc wrapup --from-summary "Decision: rejected Redis for single-VPS — broker overhead unjustified for 10KB/msg, 1-to-1 FIFO. fs.watch sufficient."

The CLI auto-classifies:

• Type: decision / lesson / finding / spike (regex hints)
• Scope: infra / perf / security / api / frontend / process

Entry format:

- [2026-04-28T15:00:00.000Z] [perf] Decision: ...

GitHub Integration (Phase 49.3)

Webhook-based notifications + UI feed for linked GitHub repos.

arc github link <project> <owner/repo>

Link a repo to a project. Returns the webhook URL, secret, and step-by-step instructions for GitHub repo Settings → Webhooks.

arc github link arc-v2 SerhiiInUa/citadel-v2

Output:

✓ Repo linked.

Webhook URL:    https://arc-os.co/api/webhooks/github
Webhook secret: <32-byte hex>

Setup instructions:
  1. Go to https://github.com/SerhiiInUa/citadel-v2/settings/hooks
  2. Click "Add webhook"
  3. Payload URL: https://arc-os.co/api/webhooks/github
  4. Content type: application/json
  5. Secret: <secret>
  6. Events: Push, Pull requests, Workflow runs, Issues

arc github links [project]

List the repos linked to a project (default: ARC_PROJECT env).

arc github links arc-v2

arc github unlink <project> <id>

Remove a link by id (from arc github links).

arc github unlink arc-v2 3

Supported events: push, pull_request, workflow_run, issues (95% of use cases).

What you get after setup:

• Telegram notification to the project owner on every event (icon + summary + GitHub link)
• Sidebar feed in the Workspace ContextRail (polls 30s, last 8 events)

Detailed setup guide: GitHub Integration Setup.

Neural Memory

arc memory refresh

Phase 71.8 (#365): re-embed all of the project's key knowledge sources (MANIFEST + ROADMAP + wiki + open issues) into the self-hosted RAG store (embeddings + embeddings_vec). Same endpoint, new semantics — writes to the local SQLite, not to Google NotebookLM.

arc memory refresh

Output:

Refreshing neural memory...
Synced: 12 | Errors: 0

Sources:
  - wiki/architecture.md
  - wiki/deploy-guide.md
  - issues/open

Timeout: 30 seconds (the volume of embed calls to Cohere for a full re-embed).

This step is usually unnecessary — the Phase 71.5 hooks automatically re-embed every wiki/issue/skill write. arc memory refresh is useful as a "force re-index" after a mass pull or a migration.

arc memory fetch-artifact — removed in Phase 71.8

The NotebookLM audio overview has no RAG equivalent. The endpoint returns 410 Gone. If you need a voice summary — see a future Phase for Whisper TTS over the project wiki.

Environment Variables

Set automatically by arc start, but you can set them manually to use subcommands outside a session.

Manual usage example (outside arc start):

export ARC_PROJECT=my-project
export ARC_SERVER_URL=https://arc-os.co
export ARC_TOKEN=eyJhbGciOiJIUzI1NiI...
arc issues
arc learnings

Session Monitoring

On arc start a background watcher launches automatically, which:

1. Finds the new .jsonl file in ~/.claude/projects/{normalized-cwd}/
2. Reads new lines from the transcript every 3 seconds
3. Parses user and assistant messages
4. Sends them to POST /api/cli/chat-log/:project (fire-and-forget)
5. Content is truncated to 10,000 characters per message

The watcher is non-critical — errors are ignored, and the session keeps working even if the CRM is unavailable.

Usage Examples

Typical workflow

# 1. Log in (one-time)
arc login

# 2. View available projects
arc projects

# 3. Start a session
arc my-project dev

# --- Inside the Claude session: ---

# 4. View open issues
arc issues

# 5. Create a new issue
arc issue create --title "Add dark mode" --priority P1 --labels "ux,frontend"

# 6. Log progress
arc issue log 42 "Started implementation"
arc issue log 42 "Toggle component ready, testing system preference detection"

# 7. Update the wiki
arc wiki update --file "architecture" --content "# Architecture\n\nUpdated with dark mode module..."

# 8. Update the roadmap
arc roadmap sync --phase 45 --status "IN PROGRESS"

# 9. Load a skill when needed
arc skill crm-api-reference

# 10. View learnings
arc learnings

# 11. Close the issue
arc issue update 42 --status closed

# 12. Send a report
arc report --summary "Implemented dark mode with system preference detection" \
  --files "theme.ts,App.tsx,DarkModeToggle.tsx" \
  --decisions "Used CSS custom properties for theming"

Memory synchronization

arc memory refresh
arc memory fetch-artifact --type audio_overview

Working with multiple projects

# Session for the first project
arc project-alpha dev

# In another terminal — a session for the second one
arc project-beta dev --role clceo

Timeouts