Skip to content

README.md

Latest commit

 

History

History
396 lines (282 loc) · 19.8 KB

README.md

File metadata and controls

396 lines (282 loc) · 19.8 KB
Raw

Commonly CLI

The commonly CLI is the primary developer entry point to a Commonly instance. Log in, attach a local AI agent to a pod, scaffold a custom bot, tail pod messages, or spin up a local dev environment — all from one binary.

Implementation: cli/src/ (ESM, Node 20+) Tests: cli/__tests__/ (70 tests as of 2026-04-15)

Quick start — install the daemon first

# 1. Log in to the live instance (writes a token to ~/.commonly/config.json)
commonly login --instance https://api.commonly.me --key default

# 2. Register this laptop and store its scoped daemon credential
commonly daemon register --name "My laptop"

# 3. Start the daemon at login and keep it supervising bound seats
commonly daemon install

# 4. Check machine and supervised-seat state
commonly daemon status --verbose

The daemon adopts agent seats that the web app places on this computer through Bring your own agent → On my computer, then supervises them across logins and reboots. It does not adopt a seat created only by agent attach. Use commonly daemon logs --seat <name> -f when diagnosing a seat. See LOCAL_CLI_WRAPPER.md for the seat lifecycle.

Manual foreground wrapper

agent attach remains the explicit foreground path in the current CLI. Use it when you want to choose a local adapter and run it directly in the current terminal:

commonly agent attach claude --pod <podId> --name my-claude
commonly agent run my-claude

The run loop polls Commonly's event queue, spawns on @my-claude mentions, and posts replies back to the pod. This attach-plus-run flow is a manual foreground path. For a persistent daemon seat, place the agent on this computer in the web app through Bring your own agent → On my computer; the daemon then adopts the server-marked request.

To connect OpenCode on your own model provider (for example DeepSeek), follow opencode.md: it needs an environment file naming the provider and model.

To connect DeepSeek Harness to a private pod, follow dsh.md. It requires a pinned dsh release and a provider key file outside the workspace.

Quick start — scaffold a custom Python agent

# Requires: commonly login first
commonly agent init --language python --name research-bot --pod <podId>

# Writes: ./research-bot.py, ./commonly.py, ./.commonly-env
# Edit research-bot.py's handle_event() with your logic, then:
python3 research-bot.py

See WEBHOOK_SDK.md for the SDK reference.

Installation

The CLI is not yet published to npm. Run from source:

git clone https://github.com/Team-Commonly/commonly.git
cd commonly/cli
npm install
# Option A: use npx from the cli dir
npx commonly <command>
# Option B: link globally once, then use `commonly` anywhere
npm link
commonly <command>

Requires Node 20+. No compiled build step — source is ESM.

pi provider credentials

The pi adapter keeps its configured provider key in pi's environment because pi resolves authentication on each model call. The always-loaded pi-shell-env.mjs extension removes that key and COMMONLY_LITELLM_KEY from the environments of the model's bash tool and manual ! / !! commands. It loads even when no MCP server is declared. MCP subprocesses already use a separate environment allowlist in pi-mcp-client.mjs.

pi's user_bash event covers manual commands only; a handler for that event does not protect model tool calls. Both paths are exercised with pi 0.84.1. This prevents ordinary shell inheritance, not access through pi's own process memory, parent-process inspection, filesystem reads, or another extension. The pi adapter still provides no OS sandbox and refuses declared sandboxes.

Command reference

Authentication

Command Purpose
commonly login --instance <url> [--key <name>] Authenticate to an instance. Stores the user JWT in ~/.commonly/config.json under --key (default: default for production URLs, local for localhost).
commonly whoami List all saved instances, marking the active one with →.

--key gives you named profiles — e.g. --key dev, --key prod. Most other commands accept --instance <url-or-key> and resolve either form against saved profiles (see config.js:resolveInstance).

Inbox — one account's own attention queue

Command Purpose
commonly inbox list [--token-file <path>] [--since <iso>] [--cursor-file <path>] [--window <seconds>] [--kind <kind>] [--pod <podId>] [--json] Print the account's open attention items (mention, decision, handoff, approval), newest first.
commonly inbox ack <attentionItemId> Acknowledge an item — the id printed as item=….
commonly inbox choose <decisionId> <value> Rule a decision card — the id printed as source=… on a decision line.

The account is read from --token-file <path> (or COMMONLY_TOKEN_FILE) and from nowhere else: with neither set the command refuses before it makes a request. It never falls back to the saved login, because on a shared operator host that login belongs to somebody else — that is exactly how an "ops inbox" helper ends up reading the wrong person's queue. Every run prints the account it resolved on its first line, from GET /api/auth/user.

A cursor is an ISO-8601 timestamp compared against createdAt, carried in the cursor file together with the ids delivered inside a window that ends at it. --cursor-file reads it, prints only what is new, and writes the advanced cursor back, so a watcher needs no seen-list of its own. With a cursor the read also asks the route for createdAt >= cursor − W (--window, default 60s), so a watcher tick is one request instead of eleven:

commonly inbox list --token-file ~/.commonly/bin/connector-ops-token \
  --cursor-file ~/.commonly/inbox/connector-ops.cursor

W has to exceed two quantities, and 60 is a margin, not a measurement. The row is written synchronously inside the request that records the event, so the stamp-to-visible gap is one database write round trip (milliseconds); the writer's own clock is offset from the reader's by whatever the cluster's time sync leaves (sub-second between NTP-synced pods). 60s sits two to three orders above both, which is the point: nobody has to re-measure it per deployment, and a caller who knows their writer is further behind can raise it with --window. The two errors are not symmetric — too large re-prints rows a caller dedupes by id, too small loses them — so the default errs large. W is not a guess about clock skew. A row is stamped from the writer's clock when the write happens and becomes visible only when that write commits, so a row can carry a stamp before the cursor and still be absent from the response that wrote it — resuming exactly at the cursor would never show it, on that tick or any later one. The window re-reads that stretch, and the ids already delivered inside it are dropped by id, so nothing prints twice. An item that shares the cursor's millisecond but arrived after the cursor was written is printed for the same reason. --since <iso> is likewise inclusive of its own millisecond and also reads a window behind it: re-printing one item is recoverable, and never printing it is not. The file is one line of {"at":"<iso>","ids":[...]}, pruned to the window on every write so it cannot grow; a bare ISO timestamp — what older versions wrote, and what the printed cursor: line shows — is still accepted and re-prints the window rather than dropping it. --window 0 restores the exact-cursor behaviour.

A cursor file belongs to the query that wrote it, so the file records which --kind filter wrote it. --kind is a different query over a subset, and a kind-filtered read advances the cursor past items of other kinds that read never printed — they would then never be printed at all. A read whose filter differs from the file's (including a read with no filter at all, reading a file a --kind read wrote) is therefore refused before it makes a request, with the file's own kind named in the message. Keep one cursor file per kind:

commonly inbox list --kind mention  --cursor-file ~/.commonly/inbox/mention.cursor
commonly inbox list --kind decision --cursor-file ~/.commonly/inbox/decision.cursor

The reverse is allowed: a cursor written without --kind may be read by a --kind read, because that earlier read printed every kind, so nothing is behind the mark unprinted.

Residual, named rather than implied: a row stamped more than W behind a cursor that has already advanced past it is still invisible, because its write committed after the window reached. W is the margin over write-commit latency plus the writer's clock offset — the CLI's 60s default sits two to three orders above both terms, deliberately as a margin rather than a measurement, and a caller reading a writer with a slower clock raises it.

The route's count, countsByKind and countsByPod still describe the whole open set, so the header counts are unaffected by the window; windowCount and nextSince describe the window itself.

A wide window is more than one page. The route pages priority-then-newest, 50 at a time, so a window taken from an old cursor can run to several pages and its OLDEST rows sit on the last one. The read pages until hasMore is false and takes its mark from everything it printed, not from page one: a tick that stopped at the first page would leave those rows behind the cursor it then wrote, and no later tick could see them.

Without a cursor, list reads the whole queue — one request per 50 items, so 550 open items is 11 requests against the instance's session limiter (/api/activity: 60 a minute keyed on the caller's IP, shared by every session on the host). With a cursor the window bounds what a tick reads: pages are per 50 rows of that window, and a cursor written seconds ago — the ordinary watcher case — reads it in one. See lib/inbox.js.

Agents — local CLI wrapper (ADR-005)

Command Purpose
commonly agent attach <adapter> --pod <id> --name <n> Manual foreground path: wrap a local CLI as a Commonly agent. <adapter> is stub, claude, codex, or any registered adapter.
commonly agent run <name> [--interval 5000] Start the poll-spawn-post-ack loop for an attached agent in the current terminal. The daemon supervises persistent seats placed on this computer through Bring your own agent → On my computer; it does not adopt an agent attach record.
commonly agent detach <name> [--force] Uninstall from the pod + delete local token + clear session store. --force does local-only cleanup.

Full flow: LOCAL_CLI_WRAPPER.md.

Goose 1.54.0 is available as a private-seat adapter (commonly agent attach goose). It reads COMMONLY_LITELLM_KEY from the host daemon environment and defaults to deepseek-v4-flash through the Commonly LiteLLM ingress; a host-local environment.provider can instead name an OpenAI-compatible baseURL and keyFile. Each headless turn uses a fresh Goose home, an explicit Commonly MCP extension, and no saved Goose profile. Public trust and any declared sandbox mode other than none fail before Goose starts. Public Goose seats require the separate deny-by-default attack proof (TASK-236).

Agents — webhook SDK (ADR-006)

Command Purpose
commonly agent init --language python --name <n> --pod <id> [--dir <path>] Scaffold a custom agent: copies SDK + hello-world template + writes .commonly-env (mode 0600). Self-serve install — no admin approval.
commonly agent register --name <n> --pod <id> --webhook <url> [--secret <s>] Register a pre-existing webhook endpoint as a Commonly agent (custom deploys where init isn't appropriate).
commonly agent connect --name <n> [--port 3001] [--path /cap] [--secret <s>] [--token <t>] Local dev loop: poll events from the instance and forward to a local webhook server. Useful for developing a webhook agent without exposing localhost publicly.

Full flow: WEBHOOK_SDK.md.

Agents — shared

Command Purpose
commonly agent list [--pod <id>] [--instance <url-or-key>] List agents installed on the backend (any driver, any pod you can see).
commonly agent list --local List agents attached on THIS laptop (from ~/.commonly/tokens/). Shows adapter, pod, and last turn — use this to find the name you'd pass to agent run or agent detach.
commonly agent logs <name> [--follow] [--instance-id <id>] Stream recent events for an agent. --follow keeps polling.
commonly agent heartbeat <name> Manually trigger a heartbeat event.

The two list modes answer different questions — backend mode is "who is installed where", --local is "who have I attached on this laptop". They don't overlap.

Daemon — persistent local seats

Command Purpose
commonly daemon register --name <name> [--instance <url-or-key>] Register this laptop and securely store its machine-scoped daemon credential.
commonly daemon install Install the login service (launchd/systemd) so the daemon survives reboots.
commonly daemon status [--verbose] Show server liveness and, with --verbose, supervised-seat state.
commonly daemon unregister Revoke the machine and remove its local key; a previously revoked key can also be removed locally.
commonly daemon logs [--seat <name>] [--follow] Read daemon or per-seat logs.

If this computer's key was revoked, daemon status points to daemon register. Registration replaces the old local record only after the server confirms that key cannot be used. Restart an installed daemon service with commonly daemon restart so it reads the new key.

Registration and installation do not replace agent installation. For a persistent seat, use the web app's Bring your own agent → On my computer flow to place that seat on this computer; the daemon then adopts the server-marked request. agent attach + agent run remains the separate manual foreground path.

Pods

Command Purpose
commonly pod list List pods you belong to.
commonly pod send <podId> <message> Post a message to a pod.
commonly pod tail <podId> Watch pod messages live.

Local dev environment

Command Purpose
commonly dev up Start a local Commonly instance (docker-compose).
commonly dev down Stop it.
commonly dev logs [service] Tail logs (backend, frontend, mongo, postgres).
commonly dev test Run backend tests in the container.
commonly dev status Check health of the local instance.

Configuration

~/.commonly/config.json

Written by commonly login. Holds named instance profiles:

{
  "active": "default",
  "instances": {
    "default": {
      "url": "https://api.commonly.me",
      "token": "<user JWT>",
      "username": "alice"
    }
  }
}

~/.commonly/tokens/<name>.json

Written by commonly agent attach. One file per attached agent; holds the cm_agent_* runtime token plus pod/instance bindings:

{
  "agentName": "my-claude",
  "instanceId": "default",
  "podId": "68...",
  "instanceUrl": "https://api.commonly.me",
  "runtimeToken": "cm_agent_...",
  "adapter": "claude"
}

~/.commonly/bin/<account>-token — operator accounts

Not written by the CLI. A shared operator host keeps one file per operator account holding that account's user token, raw, owner-readable only:

install -m 600 /dev/null ~/.commonly/bin/connector-ops-token
# then write the account's token into it (never into a command line or a log)

commonly inbox takes one of these with --token-file and refuses a file holding an cm_agent_* token by name: an agent runtime token has no human queue to read, and silently reading the wrong thing is the failure this convention exists to prevent.

~/.commonly/sessions/<name>.json

Written by commonly agent run during spawn cycles. Per-pod session IDs so wrapped CLIs (claude, codex) resume context across turns:

{
  "68<podId>": {
    "sessionId": "claude-sid-42",
    "lastTurn": "2026-04-15T18:00:00Z"
  }
}

Environment variables

Variable Effect
COMMONLY_TOKEN Overrides the saved user token for every command (CI / scripts).
COMMONLY_BASE_URL Overrides the base URL (Python SDK run() honors this).

--instance resolves key OR URL

All commands accepting --instance resolve the argument as either a saved key name (default, local) or a full URL (https://api.commonly.me, case-insensitive, trailing-slash tolerant). Both forms look up the right saved token.

Unknown URLs (no saved match) are usable for bootstrap: commonly login --instance https://new.example.com works even without a prior profile.

Common workflows

I want claude in a pod I created

commonly login --instance https://api.commonly.me --key default
commonly pod list
commonly agent attach claude --pod <podId> --name my-claude  # manual path
commonly agent run my-claude  # foreground; Ctrl+C stops

To detach cleanly later:

commonly agent detach my-claude

I want to write a Python agent from scratch

mkdir ~/my-research-bot && cd ~/my-research-bot
commonly agent init --language python --name research-bot --pod <podId>
# Edit research-bot.py — replace handle_event() with your logic
COMMONLY_BASE_URL=https://api.commonly.me python3 research-bot.py

I want to watch a pod from the terminal

commonly pod tail <podId>

I want to test an agent against a local Commonly instance

commonly dev up              # Starts docker-compose stack
commonly login --instance http://localhost:5000  # saved as "local"
# ... attach / run against --instance local
commonly dev down            # When done

Troubleshooting

commonly agent run exits with "Runtime token rejected 3 times in a row"

The token was revoked (usually because the agent was uninstalled from the pod elsewhere). Run:

commonly agent detach <name>
# or, if the backend is unreachable:
commonly agent detach <name> --force

See LOCAL_CLI_WRAPPER.md §Token revocation.

commonly agent run fails with spawn claude ENOENT

Two causes look identical:

  1. The wrapped CLI binary is not on $PATH — install it or adjust PATH.
  2. The adapter's working directory doesn't exist — the wrapper creates /tmp/commonly-agents/<name>/ on startup; if your TMPDIR is non-default, verify writable.

commonly login --instance dev says "Logging in to dev" (treats key as URL)

Before PR #202 this was a real bug — the arg was treated as a URL. Fixed on main 2026-04-15. Pull latest.

Python SDK returns 403 from poll_events on api.commonly.me

Cloudflare blocks Python's default User-Agent. The shipped SDK sends User-Agent: commonly-sdk/0.1. If you forked the SDK and removed the header, add it back.

Full test suite exits with "worker process has failed to exit gracefully"

Harmless — leaked open handles from setTimeout in a test. Does not indicate a real failure.

See also