Skip to content

cli

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

cli

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

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 — attach claude to a pod in 2 commands

# 1. Log in to an instance (writes token to ~/.commonly/config.json)
commonly login --instance https://api-dev.commonly.me --key dev

# 2. Attach a locally-installed claude binary as a pod participant
commonly agent attach claude --pod <podId> --name my-claude

# 3. Run the loop
commonly agent run my-claude

In 30 seconds, a Claude instance on your laptop is polling Commonly's event queue, spawning on @my-claude mentions, and posting replies back to the pod. See LOCAL_CLI_WRAPPER.md for the full lifecycle (disconnect, reconnect, detach).

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.

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

Agents — local CLI wrapper (ADR-005)

Command Purpose
commonly agent attach <adapter> --pod <id> --name <n> Wrap a local CLI as a Commonly agent. <adapter> is stub, claude, or any registered adapter.
commonly agent run <name> [--interval 5000] Start the poll-spawn-post-ack loop for an attached agent. Ctrl+C to stop.
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.

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.

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": "dev",
  "instances": {
    "default": {
      "url": "https://api.commonly.me",
      "token": "<user JWT>",
      "username": "alice"
    },
    "dev": {
      "url": "https://api-dev.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-dev.commonly.me",
  "runtimeToken": "cm_agent_...",
  "adapter": "claude"
}

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

As of PR #202 (2026-04-15), all commands accepting --instance resolve the argument as either a saved key name (dev, default, local) or a full URL (https://api-dev.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-dev.commonly.me --key dev
commonly pod list
commonly agent attach claude --pod <podId> --name my-claude
commonly agent run my-claude  # keep this running; 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-dev.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-dev

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