CLI Reference: Agents
Commands for spawning, listing, inspecting, and terminating agents.
ash spawn
Spawn a new agent from a manifest file.
ash spawn <manifest>
| Argument | Description |
|---|---|
manifest | Path to the agent manifest YAML file |
Example:
ash spawn etc/agents/report-agent.yaml
ash validate
Validate an agent manifest file locally. Does not require agentd to be running.
ash validate <manifest>
Checks the manifest for structural validity (required fields, enum values, capability format). Exits 0 on success, non-zero with error messages on failure.
ash list / ash ls
List all running agents.
ash list
ash ls # alias
Output columns: AGENT ID, NAME, VERSION, STATE, TRUST.
ash info
Get detailed information about a specific agent.
ash info <agent-id>
Output includes: agent ID, name, version, trust level, lifecycle state, capabilities, parent agent (if any), and spawn time.
ash kill
Terminate a running agent.
ash kill <agent-id>
Sends a Terminate transition to the agent. The agent completes any in-progress action before shutting down.
ash transition
Manually override an agent's lifecycle state. Intended for admin/debug use.
ash transition <agent-id> <state>
Valid states: plan, act, observe, terminate.
ash discover
Discover agents by capability pattern.
ash discover <agent-id> [pattern]
| Argument | Description |
|---|---|
agent-id | Agent ID performing the discovery (must have agent.discover capability) |
pattern | Optional glob pattern to filter by capability, e.g. bus.* |
ash ping
Check if agentd is running and responsive.
ash ping
Exits 0 if agentd responds, non-zero otherwise.
ash status
Show daemon status including version, uptime, and running agent count.
ash status
Global flags
All ash commands accept:
| Flag | Default | Description |
|---|---|---|
--socket | /run/agentd/agentd.sock | Path to agentd Unix socket |
--version | - | Print ash version |