Agents CLI

The Agents CLI lets you list, inspect and run your almyty agents from a terminal or a script. Use it when a person isn’t the one starting the work: for example, a nightly script that runs your “invoice-pipeline” agent and saves the result, or a CI pipeline (the automated checks that run when code changes) that asks an agent for a release summary. In the app, the same things live on Agents; see Agents.

$ npx @almyty/agents --help

Listing agents

List all agents in your organization:

$ npx @almyty/agents list
NAME              MODE          STATUS    LAST RUN
invoice-pipeline  workflow      active    2 hours ago
research-bot      autonomous    active    12 minutes ago
data-cleanup      workflow      paused    3 days ago

Add --json for machine-readable output:

$ npx @almyty/agents list --json
[
  {
    "id": "a1b2c3d4-...",
    "name": "invoice-pipeline",
    "mode": "workflow",
    "status": "active",
    "lastRunAt": "2026-04-09T08:12:00Z"
  }
]

Getting agent details

Inspect a single agent by name or UUID:

$ npx @almyty/agents get invoice-pipeline
Name:         invoice-pipeline
ID:           a1b2c3d4-...
Mode:         workflow
Status:       active
Nodes:        6 (input -> llm_call -> tool_call -> condition -> tool_call -> output)
Created:      2026-03-15
Last run:     2 hours ago (success)

$ npx @almyty/agents get a1b2c3d4-...

Both name and UUID lookups work for every command that accepts an agent reference.

Running agents

Workflow mode

Workflow agents follow the fixed steps you drew on the canvas (a DAG, or directed graph: each step runs after the ones pointing into it), such as input, model calls, tool calls, conditions and transforms, and return a result. Each invocation is a single run:

$ npx @almyty/agents run invoice-pipeline --input '{"file_url": "https://example.com/invoice.pdf"}'
{
  "runId": "run-xyz",
  "status": "completed",
  "output": {
    "vendor": "Acme Corp",
    "amount": 1250.00,
    "currency": "USD",
    "due_date": "2026-05-01"
  }
}

The --input flag accepts a JSON string. The agent runs synchronously and prints the output when complete.

Piping output

Combine with standard Unix tools for scripting:

$ npx @almyty/agents run invoice-pipeline \
    --input '{"file_url": "https://example.com/invoice.pdf"}' \
    --json | jq '.output.amount'
1250.00

Autonomous mode

Autonomous agents decide for themselves which tools to call, step by step, until the job is done. Use --watch to stream the steps as they happen:

$ npx @almyty/agents run research-bot --input '{"topic": "quantum computing trends"}' --watch
[run-abc] Starting autonomous agent: research-bot
[step 1] llm_call: Planning research strategy
[step 2] tool_call: web-search {"query": "quantum computing 2026 breakthroughs"}
[step 3] llm_call: Analyzing search results
[step 4] tool_call: web-search {"query": "quantum error correction advances"}
[step 5] llm_call: Synthesizing findings
[step 6] output: Research complete
 
Final output:
{
  "summary": "...",
  "sources": ["..."]
}

Safety limits for autonomous runs

Autonomous agents can run indefinitely if unchecked. Use these flags to set guardrails:

$ npx @almyty/agents run research-bot \
    --input '{"topic": "AI safety"}' \
    --watch \
    --max-steps 20 \
    --max-cost-cents 500 \
    --max-duration-ms 300000

These limits apply server-side, and they only ever tighten: the organization’s settings and the operator’s RUN_LIMIT_* ceiling still apply, so a flag can lower a ceiling but never raise one.

If a limit is hit, the run terminates with status failed and an error of the form CODE: explanation. The codes are MAX_STEPS_EXCEEDED, BUDGET_EXCEEDED, TIMEOUT, TOKEN_LIMIT_EXCEEDED, TOOL_CALL_LIMIT_EXCEEDED, RECURSION_DEPTH_EXCEEDED, and CONTEXT_BUDGET_EXCEEDED. The same pair is stored on the run’s metadata under limitTrip, and whatever output the run produced up to that point is kept.

These are defaults, not ceilings. The values above apply when no scope sets anything; the operator’s environment sets a hard ceiling on top (RUN_LIMIT_MAX_DURATION_MS, 3600000 out of the box), and the organization and the agent may tighten further. A flag can only lower the limit that resolution already arrived at, never raise it past the operator ceiling. See Run limits.

Listing recent runs

View the execution history for an agent:

$ npx @almyty/agents runs invoice-pipeline
RUN ID      STATUS      STARTED           DURATION
run-xyz     completed   2 hours ago       4.2s
run-wvu     completed   5 hours ago       3.8s
run-tsr     failed      1 day ago         12.1s

Add --json for the full run details including inputs and outputs.

Canceling runs

Cancel a running autonomous agent:

$ npx @almyty/agents cancel research-bot run-abc
Run run-abc canceled.

Cancellation is best-effort. If the agent is in the middle of a tool call, the current step may complete before the run stops. Workflow agents typically finish too quickly to cancel, but the command works for both modes.

Workflow vs autonomous mode

Scripting examples

Run an agent and check the exit code

$ npx @almyty/agents run invoice-pipeline --input '{"file_url": "..."}' --json > result.json
$ if [ $? -eq 0 ]; then
    echo "Success: $(jq -r '.output.vendor' result.json)"
  else
    echo "Agent failed"
  fi

Start an autonomous agent, watch it, then cancel

# Start in the background with a 5-minute timeout
$ npx @almyty/agents run research-bot \
    --input '{"topic": "market analysis"}' \
    --watch \
    --max-duration-ms 300000
 
# In another terminal, cancel if needed
$ npx @almyty/agents cancel research-bot <run-id>

List failed runs as JSON and pipe to a report

$ npx @almyty/agents runs data-cleanup --json | jq '[.[] | select(.status == "failed")]'