CLI Reference#

The ID Agents interactive CLI is the primary interface for managing agents. Start it with npm run id-agents and use the commands below to deploy, communicate with, and manage your agents.

Starting the CLI#

npm run id-agents

The interactive CLI is a terminal interface to the manager daemon. The daemon listens on port 4100 by default and agents are assigned ports starting at 4101. The CLI itself does not bind a network port.

With a custom manager port:

npm run id-agents -- --port 5000

Or via environment variable:

MANAGER_PORT=5000 npm run id-agents

Commands#

/deploy#

Deploy agents from a YAML configuration file.

/deploy <config>

Examples:

/deploy configs/my-team.yaml
/deploy configs/production.yaml

This reads the config file, creates agent processes, assigns ports, and starts each agent's REST-AP server. For a clean, full redeploy use /deploy. To update a running team without restarting unchanged agents, use /sync instead.

/sync#

Reconcile a running team with a config file. Diffs the current state against the config, starts new agents, stops removed agents, and restarts agents whose config changed. Agents with no config changes are left untouched.

/sync <config>

Examples:

/sync configs/my-team.yaml
/sync configs/production.yaml

Unlike /deploy, which tears down the entire team and recreates it, /sync preserves running agents that haven't changed. Use /sync for incremental updates and /deploy for clean deploys.

/agents#

List all running agents with their names, ports, and status.

/agents

/agents rebuild#

Rebuild all agents. This restarts every agent process.

/agents rebuild

/agent rebuild#

Rebuild a single agent by name.

/agent <name> rebuild

Example:

/agent coder rebuild

/ask#

Send a message to an agent. The conversation session is maintained across multiple /ask calls.

/ask <agent> <message>

Examples:

/ask coder Write a hello world function in TypeScript
/ask researcher Find the latest papers on transformer architectures

/ask * (Broadcast)#

Send a message to all agents at once.

/ask * <message>

Example:

/ask * What is your current status?

/hey#

Alias for /ask. Works identically.

/hey <agent> <message>

/news#

Check recent messages and responses from an agent.

/news <agent>

Use the -l flag to see full message content:

/news -l <agent>

/clear#

Clear the conversation session with an agent (start fresh). If no agent is specified, clears all sessions.

/clear [agent]

Examples:

/clear coder
/clear

/delete#

Delete an agent and stop its process. Supports bulk deletion with confirmation.

/delete <agent>
/delete *              # Delete all agents (with confirmation)
/delete --team <name>  # Delete all agents in a team (with confirmation)

Examples:

/delete researcher
/delete *
/delete --team staging

/output#

List artifacts produced by an agent. Agents write output files to {workingDir}/output/ by convention.

/output <agent>

Example:

/output coder

/artifact#

Read a specific artifact file from an agent's output directory.

/artifact <agent> <path>

Example:

/artifact coder report.md

/register#

Register an agent onchain via ID Chain. Requires OWS_REGISTRAR_WALLET or ID_REGISTRAR_PRIVATE_KEY to be set.

/register <agent>

Example:

/register coder

This assigns the agent a permanent ENS-based identity like x.agent-15.xid.eth.

/status#

Show the status of the manager and all agents.

/status

/help#

Display the help screen with all available commands.

/help

/team#

Show, switch, or manage teams.

/team              # Show current team
/team <name>       # Switch to or create team
/teams             # List all teams
/team delete <name> # Delete a team (team must be empty -- delete agents first)

Example:

/team personal
/teams

/wallet#

Show an agent's OWS wallet addresses. Optionally filter by chain.

/wallet <agent>
/wallet <agent> eip155:1

/update#

Update agent properties after deployment.

/update <agent> --wallet
/update <agent> --name

/heartbeat#

Manage heartbeats (interval-based recurring schedules).

Heartbeats use an agent-driven model: the YAML config sets the interval (a number in seconds), and the agent reads its own HEARTBEAT.md file for the checklist of tasks to perform on each tick. The framework delivers the heartbeat; the agent decides what to do with it.

Subcommands:

Flags:

HEARTBEAT.md:

Agents can define a HEARTBEAT.md file in their working directory. This file contains the agent's own checklist -- what to inspect, verify, or report on each heartbeat tick. The framework delivers the heartbeat at the configured interval; the agent reads HEARTBEAT.md to decide what actions to take. The YAML heartbeat field is just the interval number (in seconds), not a {interval, message} object.

Examples:

# Add a heartbeat that runs every 10 minutes
/heartbeat add contracts 600 "Run security review" --delivery internal

# Add a heartbeat with a custom sender name
/heartbeat add ops 300 "Check monitoring dashboards" --sender ops-monitor

# List all heartbeats
/heartbeat

# Pause a heartbeat
/heartbeat pause hb_agent_123

# Resume a paused heartbeat
/heartbeat resume hb_agent_123

# Remove a heartbeat
/heartbeat remove hb_agent_123

/calendar#

Manage calendar events (wall-clock scheduled events).

Subcommands:

Flags:

Examples:

# Add a calendar event for X engagement Mon-Fri at 9am
/calendar add x 09:00 "mon,tue,wed,thu,fri" "Check X for tweets" --timezone America/New_York

# Add a calendar event with a custom sender
/calendar add lead 17:00 "fri" "Weekly summary" --timezone America/New_York --sender weekly-review

# Add a one-time calendar event on a specific date
/calendar add lead 08:00 "2026-04-01" "Generate monthly report" --timezone America/New_York

# List all calendar events
/calendar

# Pause a calendar event
/calendar pause cal_agent_456

# Resume a paused calendar event
/calendar resume cal_agent_456

# Remove a calendar event
/calendar remove cal_agent_456

Schedules can also be defined in the YAML config (see Configuration).

/task#

Manage tasks for coordinating work across agents.

Subcommands:

Task statuses:

Examples:

# Create a task
/task create "Fix the overflow bug" --name fix-overflow

# List all tasks
/task list

# Claim a task
/task claim fix-overflow

# Mark a task done
/task done fix-overflow

REST API: Agents can also use the Tasks REST endpoints directly (POST /tasks, GET /tasks, POST /tasks/:name/claim, POST /tasks/:name/done, DELETE /tasks/:name) instead of going through /remote. See REST-AP Protocol -- Tasks API for details.

/quit#

Exit the interactive CLI.

/quit

Remote API#

The Manager exposes a /remote endpoint that lets any external tool -- including another Claude Code session -- interact with your agent team programmatically. This is how you manage agents from outside the interactive CLI.

From a terminal or script:

curl -X POST http://localhost:4100/remote \
  -H "Content-Type: application/json" \
  -d '{"command":"/agents"}'

From another Claude Code session: If you're working in Claude Code on a different project, you can dispatch tasks to your agent team without leaving your current session:

# Ask an agent to do something
curl -s -X POST http://localhost:4100/remote \
  -H "Content-Type: application/json" \
  -d '{"command":"/ask contracts Review the latest changes"}'

# Check for the reply
curl -s -X POST http://localhost:4100/remote \
  -H "Content-Type: application/json" \
  -d '{"command":"/news contracts"}'

This means any Claude Code instance on the same machine can coordinate with your agent team -- dispatching work, checking results, and managing the fleet.

Available remote commands:

No authentication is required. The /remote endpoint has no auth.

Admin Control Skill#

The admin-control skill lets any Claude Code session manage your agent team programmatically. Install it in a separate Claude Code project and it gives that session full control over your fleet -- dispatching work, polling for results, and sending messages to the manager.

The skill provides three communication patterns:

1. Remote commands -- Send CLI commands to the manager via /remote (as shown above). This is the simplest pattern for one-off operations like checking status or deploying configs.

2. Talk to manager -- Start a temporary HTTP listener, then send a message to the manager via /talk. The manager processes the message with its LLM and sends a reply back to the listener. Use this for conversational interactions where you want the manager to reason about your request.

# Start a listener on port 4050, send a message, wait for reply
./start-listener.js &
curl -s -X POST http://localhost:4100/talk \
  -H "Content-Type: application/json" \
  -d '{"message": "What agents are running and what are they working on?", "reply_to": "http://localhost:4050/news"}'

3. Polling for replies -- Dispatch work to agents via /ask (through /remote), then poll each agent's /news endpoint for responses with timestamp filtering. Use this for parallel fan-out work.

# Dispatch work to multiple agents
BEFORE=$(date +%s)000
curl -s -X POST http://localhost:4100/remote \
  -H "Content-Type: application/json" \
  -d '{"command":"/ask agent-1 Review the auth module"}'
curl -s -X POST http://localhost:4100/remote \
  -H "Content-Type: application/json" \
  -d '{"command":"/ask agent-2 Review the payments module"}'

# Poll for responses (timestamp filtering to only get new items)
curl -s "http://localhost:4102/news?since=$BEFORE"

Example workflow -- threshold-based completion:

Dispatch a review task to 7 agents and wait until at least 5 have responded:

# 1. Record the timestamp before dispatching
BEFORE=$(date +%s)000

# 2. Fan out work to all agents
for agent in agent-1 agent-2 agent-3 agent-4 agent-5 agent-6 agent-7; do
  curl -s -X POST http://localhost:4100/remote \
    -H "Content-Type: application/json" \
    -d "{\"command\":\"/ask $agent Review the latest security changes\"}"
done

# 3. Poll until 5 of 7 agents have responded
DONE=0
while [ $DONE -lt 5 ]; do
  DONE=0
  for port in 4101 4102 4103 4104 4105 4106 4107; do
    COUNT=$(curl -s "http://localhost:$port/news?since=$BEFORE" | jq '.items | length')
    [ "$COUNT" -gt 0 ] && DONE=$((DONE + 1))
  done
  sleep 5
done
echo "Threshold reached: $DONE agents completed"

Scripts included with the skill:

Environment variables:

Development Commands#

These npm scripts are available for development:

npm run build           # Compile TypeScript
npm run dev             # Development mode with hot reload
npm run id-agents       # Start the interactive CLI
npm test                # Run tests