11agents CLI

Local CLI for connecting AI coding runtimes to the 11agents control plane.

Install

npm install -g @11agents/cli@latest

The CLI requires Node.js 22 or newer.

Android publishing machines can opt into mobile runtime setup during install:

ELEVENAGENTS_INSTALL_MOBILE=1 npm install -g @11agents/cli@latest

If setup must fail the npm install when Python/Appium prerequisites cannot be prepared, use ELEVENAGENTS_REQUIRE_MOBILE=1.

Configure

export GTM_WRITES_TOKEN="<control-plane-token>"
export ELEVENAGENTS_MACHINE="mac-mini-01"

The default control plane is https://app.11agents.ai. Set ELEVENAGENTS_SERVER only when targeting a local or custom deployment:

export ELEVENAGENTS_SERVER="http://localhost:8082"

To point the CLI at staging (or any other base URL) for a single run, use --base-url or ELEVEN_AGENT_CLI_BASE_URL:

11agents knowledge sync --project demo --base-url https://staging.11agents.ai
# or
export ELEVEN_AGENT_CLI_BASE_URL="https://staging.11agents.ai"

Add --verbose to any command to print [LEVEL] message observability logs (colorized by level) for every network request and knowledge-base sync step before it runs:

11agents knowledge sync --project demo --verbose

Login (recommended over manually copying a token)

11agents login

This prints a pairing link (and best-effort opens it in your browser). Approve it while logged into the web app as a tenant admin, and the CLI writes the tenant's GTM_WRITES_TOKEN to ~/.11agents/env plus an idempotent hook in ~/.zshrc/~/.bashrc/~/.zprofile (whichever exist). The CLI cannot modify your current shell's environment — after a successful login, run source ~/.11agents/env or open a new terminal.

ELEVENAGENTS_MACHINE is optional. The CLI persists the selected identity in ~/.11agents/machine.json; if no identity has been saved yet, it uses the local hostname once and then keeps that value across restarts. Pass --machine or set ELEVENAGENTS_MACHINE to intentionally replace the saved identity.

On startup, the CLI prints its current version and target server to stderr. It also checks npm for a newer @11agents/cli package and prints an upgrade command when one is available.

When syncing project data, the CLI chooses tokens in this order: explicit tool/command token, GTM_SWARM_TOKEN, then the daemon control token as a compatibility fallback. The CLI does not read ~/.11agents/credentials.

After changing environment tokens or upgrading the CLI, restart the daemon:

npm install -g @11agents/cli@latest
11agents --version
11agents daemon stop
11agents daemon start --background

Runtime Pool

Scan local AI runtimes:

11agents runtime scan

Register this machine and its detected runtimes:

11agents runtime register

Run the foreground daemon:

11agents daemon start

daemon start automatically runs runtime register up front whenever --token or GTM_WRITES_TOKEN is set, so both foreground and --background runs report a registration failure immediately instead of only surfacing it in the daemon log. Without a token, daemon start skips this pre-check and proceeds to the daemon's own required registration step.

Run the daemon in the background:

11agents daemon start --background
11agents daemon status
11agents daemon stop

Background mode writes its pid to ~/.11agents/daemon.pid and logs to ~/.11agents/daemon.log.

Inspect daemon and task execution logs:

11agents logs daemon --tail 200
11agents logs task <taskId> --project <slug>

Open a local runtime queue dashboard:

11agents web
11agents web --port 4789 --no-open

Useful daemon options:

11agents daemon start --heartbeat-interval 15 --scan-interval 60 --task-interval 15 --project-refresh-interval 1800
11agents daemon start --handler ./worker.js

On startup, and every 30 minutes after that, the daemon syncs project metadata and prepares local project headquarters:

• Project headquarters: ~/.11agents/<project>/
• Project knowledge base: ~/.11agents/<project>/knowledge_base/
• Agent QMD memory: ~/.11agents/<project>/agents/<agent>/memory/
• Agent-local skills: ~/.11agents/<project>/agents/<agent>/skills/
• Cloud database snapshot: ~/.11agents/<project>/database/snapshot.json
• Task scratch directory: ~/.11agents/<project>/tmp/<taskId>/
• Task execution logs: ~/.11agents/<project>/runs/<taskId>/
• Current claimed task markers: ~/.11agents/claims/<taskId>.json

Codex runs from ~/.11agents/<project>/ by default. Treat that directory as read-only project context. Task code may write temporary files only under ./tmp/<taskId>/; the daemon removes that task scratch directory after the task finishes. Agent environment variables from the control plane are injected into the Codex child process and are not written to disk. Each run directory stores prompt.md, raw Codex JSONL in stdout.log, readable Codex dialogue in transcript.log, stderr.log, last_message.md, completion.json, and meta.json.

The built-in Codex worker starts task executions with codex --yolo exec --json --output-last-message <run>/last_message.md and prefixes the task prompt with /goal by default so remote runtime tasks can run without approval prompts or sandbox restrictions. To opt a daemon back into a Codex sandbox, start it with --codex-sandbox read-only, --codex-sandbox workspace-write, or --codex-sandbox danger-full-access.

The built-in task runner currently supports Codex tasks. A custom handler may export:

export async function handleRuntimeTask(task) {
  return {
    status: 'in_review',
    comment: `Handled task ${task.id}`,
    memory_delta: ''
  }
}

Mobile Runtime

@11agents/cli bundles the Android device-pool runtime that used to live in android-group-control-mvp: Python device_control, platform configs, mobile publish skills, data templates, and the Appium smoke script. Runtime state is kept outside the npm package:

• Mobile home: ~/.11agents/mobile or ELEVENAGENTS_MOBILE_HOME
• Python venv: ~/.11agents/mobile/.venv
• Device/account data: ~/.11agents/mobile/data
• Screenshots/UI dumps: ~/.11agents/mobile/artifacts
• Task logs: ~/.11agents/mobile/runs/<task_id>/log

Prepare a publishing machine:

11agents mobile setup
11agents mobile doctor --json

setup creates the Python venv, installs the bundled Python runtime, installs local Appium npm dependencies, installs UiAutomator2 into APPIUM_HOME, and seeds example data/config files without overwriting existing runtime data.

Core commands:

11agents mobile list-adb
11agents mobile list-devices --health --json
11agents mobile ensure-appium --device D03 --json --task-id TASK_123
11agents mobile publish-tiktok --device D03 --video /path/video.mp4 --caption "..." --json --task-id TASK_123
11agents mobile publish-instagram --device D03 --post-type reel --video /path/video.mp4 --caption "..." --json --task-id TASK_123
11agents mobile publish-facebook --device D03 --post-type text --text "..." --json --task-id TASK_123
11agents mobile publish-reddit --device D02 --post-type text --subreddit test --title "..." --body "..." --json --task-id TASK_123
11agents mobile publish-x --device D03 --post-type text --body "..." --json --task-id TASK_123
11agents mobile publish-xiaohongshu --device D03 --publish-package /path/publish_package.json --json --task-id TASK_123

Post-publish data recovery:

11agents mobile list-publish-records --json --task-id TASK_123
11agents mobile data collect --platform reddit --record-id pub_123 --json --task-id TASK_123
11agents mobile data collect --platform tiktok --scope video --device D03 --record-id pub_123 --json --task-id TASK_123
11agents mobile data collect --platform xiaohongshu --record-id pub_123 --copy-link --json --task-id TASK_123

Unsupported collectors return missing_access; provide an API token, export, or manual values and append them with 11agents mobile add-metrics.

Hosted MCP

Runtime agents and MCP clients should use the hosted project MCP endpoint:

{
  "mcpServers": {
    "11agents-project-sync": {
      "url": "https://app.11agents.ai/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer $PROJECT_SWARM_TOKEN"
      }
    }
  }
}

The hosted server exposes project-scoped tools such as:

• knowledge_sync — pull/push the project knowledge base between cloud and ~/.11agents/<project>/knowledge_base/.
• database_sync — pull/push the cloud project database snapshot.
• agent_planning — list, import, generate, and dispatch agent calendar work.
• agent_config — read or update DB-backed project agent descriptions/config and attached skill bundles.

Telemetry Compatibility

The package still includes the original gtm-swarm binary for swarm telemetry compatibility.

export GTM_SWARM_SERVER="https://<your-11agents-platform>"
export GTM_SWARM_TOKEN="<workspace-swarm-token>"
export GTM_SWARM_WORKSPACE="flatkey"
export GTM_SWARM_AGENT="x-growth-agent"
export GTM_SWARM_NODE="mac-mini-01"

gtm-swarm validate examples/x-agent-batch.json
gtm-swarm push batch examples/x-agent-batch.json

Publish

First public release should go out on the beta dist-tag:

npm login
npm test
npm pack --dry-run --json
npm publish --tag beta