@armalo/cli

Command-line tools for Armalo AI agent trust, pacts, evals, swarms, rooms, escrow, MCP, and CodeFlywheel.

Install

npm install -g @armalo/cli

Or run without a global install:

npx armalo --help

See all @armalo packages on npm.

Authenticate

Most commands use an Armalo API key. Pass it for one command:

armalo --api-key "$ARMALO_API_KEY" score get agent_abc123

Or configure a reusable profile:

armalo config set apiKey "$ARMALO_API_KEY"
armalo config set baseUrl https://www.armalo.ai

Common Commands

armalo welcome
armalo chat "what should we work on next?" --target cto
armalo -p "inspect this repo and propose the safest next patch"
armalo run
armalo run "add focused tests for the eval status command"
armalo agent --help
armalo pact --help
armalo eval --help
armalo score --help
armalo swarm --help
armalo room --help
armalo harness --help
armalo codeflywheel --help
armalo update --check

Native Agent Chat

The default armalo command now starts a native hosted Armalo agent chat. It uses your Armalo API key and the hosted swarm-chat control plane, not local Claude Code credentials:

export ARMALO_API_KEY=pk_...
armalo welcome
armalo
armalo chat "audit the current launch blockers" --target operator
armalo chat --thread <thread-id>

armalo welcome prints the terminal-native start surface without requiring API auth, so new users can see the available lanes and the addressable swarm roles before configuring a profile.

For local coding-agent work, use the Claude/Codex-style one-shot prompt form or the interactive REPL:

armalo -p "fix the failing eval test and explain the verification"
armalo --prompt "audit SDK docs for stale endpoints" --model claude-sonnet-4-6
armalo run
armalo run "write tests for swarm status"

armalo -p/armalo --prompt runs one local coding-agent turn and exits. armalo run without a prompt starts the interactive local REPL; armalo run "..." remains the explicit headless form. These local commands shell out to the configured user-owned local provider and do not charge hosted Armalo swarm-chat credits.

Use your own OpenAI Codex OAuth / ChatGPT Max Plan

Armalo can use the same local Codex CLI OAuth setup that Codex itself uses. It never stores OpenAI OAuth tokens in ~/.armalo/config.json; the only persisted Armalo setting is the selected local provider/model, while Codex reads its own ~/.codex/auth.json at runtime.

armalo config codex-oauth --login --enable  # launch codex login, then enable Codex OAuth
armalo config codex-oauth                   # redacted readiness check
armalo -p "reply exactly ok"

# one-off override without changing config:
armalo --provider openai-codex-oauth -p "inspect this repo"
armalo run --provider claude "use Claude Code for this turn"

For explicit provider config, use:

armalo config local-provider openai-codex-oauth --model gpt-5.5
armalo config default-mode coding
armalo config local-provider claude --model claude-sonnet-4-6
armalo config default-mode chat

Chat waits for a persisted agent reply. If the hosted reply worker records a terminal system failure, the CLI prints that failure instead of silently timing out. Hosted chat is credit-gated server-side so token usage can be charged to the API key's Armalo account.

Run the machine-readable capability and eval map:

armalo capabilities --json

Update

Trigger a CLI update directly from Armalo:

armalo update
armalo update --check
armalo update --dry-run

armalo update upgrades the published @armalo/cli package with your detected global package manager. armalo upgrade is an alias for the same command.

Capability Boundaries

The CLI currently supports:

• Local/offline work: profile management, built-in harness templates, local repo flywheel scans, CodeFlywheel mission ledgers, local eval checks, and dry-run swarm deployment plans.
• Hosted trust and operating-system work: agents, pacts, scores, swarms, rooms, sessions, memory, shield, marketplace, transactions, escrow, Codex tasks, and hosted CodeFlywheel sync.
• Credit- or plan-sensitive work: jury evaluation, hosted evals, Sentinel red-team runs, Cortex memory compression/relevance, context-pack ingestion/scanning, OpenClaw managed compute, and manual flywheel cycles.

The CLI should not treat valuable hosted work as free. Expensive or admin-like surfaces must stay API-key gated and server-enforced for scopes, plan, quota, tenancy, and credits. Local commands can help prepare evidence, but hosted mutation, model calls, managed compute, and red-team/eval workloads need authenticated Armalo control-plane checks.

Known gaps to keep improving:

• one generated command contract for CLI docs, MCP tools, SDK parity, and eval coverage;
• shared authz/cost preflight before expensive hosted commands;
• dry-run and rollback hints for every mutating command;
• installed-package CLI smoke tests that cover local, API-key, and credit-gated command classes.

CodeFlywheel

Inspect Armalo's coding-agent harness blueprint:

armalo harness builtin
armalo harness flywheel --prompt
armalo codeflywheel blueprint

Safety

The npm package ships only the compiled CLI in dist/, the executable shim in bin/, package.json, and this README. It does not publish repository source, local environment files, test output, or workspace metadata.

Requirements

• Node.js 24.x

License

MIT