@agentage/cli

@agentage/cli

CLI and daemon for the Agentage control plane. Discovers local agents, executes them, and connects to the hub for multi-machine orchestration.

Installation

npm install -g @agentage/cli

Quick Start

# Start the daemon (discovers agents, exposes REST API)
agentage daemon

# List discovered agents
agentage agents

# Run an agent
agentage run my-agent "Summarize this project"

# Check daemon + hub status
agentage status

Daemon

The daemon is a lightweight Express server that runs on each machine. It discovers local agents, executes them, and optionally syncs with a central hub.

API

Method	Endpoint	Description
GET	/api/health	Status, version, uptime, machine ID, hub connection
GET	/api/agents	List discovered agent manifests
POST	/api/agents/refresh	Re-scan agent directories
POST	/api/agents/:name/run	Execute an agent ({ task, config?, context? })
GET	/api/runs	List all runs
GET	/api/runs/:id	Get run details + output
POST	/api/runs/:id/cancel	Cancel a running execution
POST	/api/runs/:id/input	Send input to a waiting agent

Default port: 3100

Agent Discovery

The daemon scans configured directories for agents:

~/.agentage/agents/*.agent.md    # Global agents
.agentage/agents/*.agent.md      # Workspace agents

Two built-in factories: markdown (.agent.md files with YAML frontmatter) and code (TypeScript/JavaScript modules exporting an Agent).

Hub Sync

When authenticated (agentage login), the daemon connects to the hub via WebSocket — registering the machine, syncing agents, and relaying run events.

Method	Endpoint	Description
GET	/api/hub/machines	List all hub-connected machines
GET	/api/hub/agents	Aggregated agents across all machines
POST	/api/hub/runs	Start a run on any connected machine

CLI Commands

Command	Description
agentage daemon	Start the daemon server
agentage agents	List discovered agents
agentage run <name> [task]	Execute an agent
agentage runs	List runs
agentage machines	List hub-connected machines
agentage status	Show daemon and hub status
agentage logs	View daemon logs
agentage login	Authenticate with the hub
agentage logout	Log out

Project Structure

src/
├── cli.ts                  # CLI entry point (commander)
├── daemon-entry.ts         # Daemon process entry point
├── commands/               # CLI command handlers
│   ├── daemon-cmd.ts       #   agentage daemon
│   ├── agents.ts           #   agentage agents
│   ├── run.ts              #   agentage run
│   ├── runs.ts             #   agentage runs
│   ├── machines.ts         #   agentage machines
│   ├── status.ts           #   agentage status
│   ├── logs.ts             #   agentage logs
│   ├── login.ts            #   agentage login
│   └── logout.ts           #   agentage logout
├── daemon/                 # Daemon server
│   ├── server.ts           #   Express + HTTP server setup
│   ├── routes.ts           #   REST API routes
│   ├── config.ts           #   Daemon configuration
│   ├── run-manager.ts      #   Agent execution + run lifecycle
│   ├── websocket.ts        #   WebSocket for streaming
│   └── logger.ts           #   Structured logging
├── discovery/              # Agent discovery
│   ├── scanner.ts          #   Directory scanning
│   ├── markdown-factory.ts #   .agent.md parser (gray-matter)
│   └── code-factory.ts     #   JS/TS module loader (jiti)
├── hub/                    # Hub connection
│   ├── auth.ts             #   Auth token storage
│   ├── auth-callback.ts    #   OAuth callback server
│   ├── hub-client.ts       #   Hub REST client
│   ├── hub-sync.ts         #   Machine/agent sync
│   ├── hub-ws.ts           #   Hub WebSocket client
│   └── reconnection.ts     #   Auto-reconnect logic
└── utils/
    ├── daemon-client.ts    #   CLI → daemon HTTP client
    ├── ensure-daemon.ts    #   Auto-start daemon if not running
    └── render.ts           #   Terminal output formatting

Development

Requires Node.js >= 22.0.0.

npm ci
npm run verify    # type-check + lint + format + test + build
npm run build && npm link   # test CLI locally

License

MIT