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"

ELEVENAGENTS_MACHINE is optional. If omitted, the CLI uses the local hostname.

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.

Project-scoped MCP, knowledge-base sync, and database sync tokens can be stored in ~/.11agents/credentials:

# tokens:
flatkey: gtm_xxxxxxxxxxxxxxxxxxxx
voc-ai: gtm_yyyyyyyyyyyyyyyyyyyy

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

For runtime tasks, token lookup tries the cloud workspace.slug, cloud workspace.name, --project, and --workspace. Use the project slug when you know it; adding the display name is also safe when the slug/name differ:

# tokens:
flatkey-prod: gtm_xxxxxxxxxxxxxxxxxxxx
Flat Key: gtm_xxxxxxxxxxxxxxxxxxxx

The credentials file must live under the same HOME used by the daemon process. If the daemon is launched by a service manager or SSH session under a different user, confirm with 11agents daemon status and check that user has the file at ~/.11agents/credentials. After changing credentials 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

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>

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 marker: ~/.11agents/claim_id

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.

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