@rayenbenabdallah/agentos-cli

CLI for AgentOS — agent management, memory, policy, audit, and federation.

What is this?

@rayenbenabdallah/agentos-cli is the official command-line interface for the AgentOS platform. It provides full access to the AgentOS API from your terminal — manage agents, write and query memory, create and evaluate policies, export and verify audit bundles, run federation workflows, and more.

    _                      __   ____   _____
   / \   __ _  ___ _ __   / /_ / __ \ / ___/
  / _ \ / _` |/ _ \ '_ \ / __// / / /\__ \
 / ___ \ (_| |  __/ | | / /_ / /_/ /___/ /
/_/   \_\__, |\___|_| |_|\__/ \____//____/
         |___/                 AgentOS CLI

Installation

npm install -g @rayenbenabdallah/agentos-cli
# or
pnpm add -g @rayenbenabdallah/agentos-cli

After installation, the agentos command is available globally.

Quick Start

# 1. Check that everything is working
agentos doctor

# 2. Generate Ed25519 keypairs
agentos keygen --out ./keys

# 3. Run the full end-to-end demo
agentos --base-url http://localhost:3000 demo run

Configuration

The CLI reads configuration from multiple sources (in priority order):

1. CLI flags — --base-url, --tenant-id, --agent-id, etc.
2. Environment variables — AGENTOS_BASE_URL, AGENTOS_TENANT_ID, etc.
3. .env file — Loaded automatically (override with --env-file <path>).
4. Persisted state — .agentos/state.json stores IDs from previous commands (e.g., agentId from agent register).

Global Options

| Flag | Env Variable | Description | |------|-------------|-------------| | --base-url <url> | AGENTOS_BASE_URL | API base URL | | --tenant-id <id> | AGENTOS_TENANT_ID | Tenant ID | | --tenant-api-key <key> | AGENTOS_TENANT_API_KEY | Admin API key | | --agent-id <id> | AGENTOS_AGENT_ID | Agent ID | | --version-id <id> | AGENTOS_VERSION_ID | Version ID | | --key-id <id> | AGENTOS_KEY_ID | Key ID | | --private-key <key> | AGENTOS_PRIVATE_KEY | Ed25519 private key (base64) | | --env-file <path> | — | Path to .env file (default: .env) | | --json | — | Output raw JSON |

Commands

keygen — Generate Ed25519 Keypairs

agentos keygen --out ./keys
# Writes public.key and private.key to ./keys/

doctor — Health Check

agentos doctor
# AgentOS Health Check
#   API: OK
#   Database: OK
#   Redis: OK
#   Signing: OK

agent — Agent Operations

# Register a new agent with initial version and Ed25519 public key
agentos agent register \
  --name support-agent \
  --artifact-hash sha256:abc123 \
  --semver 1.0.0 \
  --public-key "$AGENT_PUBLIC_KEY"

Registration automatically stores the agentId, versionId, and keyId in local state for subsequent commands.

namespace — Memory Namespace Operations

# Create a namespace
agentos namespace create --name support --visibility tenant

# List namespaces
agentos namespace list

memory — Memory Operations

# Write a memory item (signed by agent key)
agentos memory write \
  --namespace-id ns_demo \
  --type episodic \
  --content "Customer reported login loop after password reset"

# Semantic memory search
agentos memory query \
  --task-type support_triage \
  --query "login issue" \
  --topk 8

policy — Policy Operations

# Create a policy from a JSON file
agentos policy create --file policy.json

# Evaluate an intent against a policy (signed)
agentos policy evaluate \
  --policy-id pol_demo \
  --intent-file intent.json

decision — Decision Operations

# Create a signed decision record
agentos decision create \
  --intent-file intent.json \
  --policy-eval-id eval_demo \
  --goal "Resolve ticket #1234" \
  --plan-summary "Lookup context, reply to customer"

action — Action Operations

# Log a signed action to the hash chain
agentos action log \
  --intent-file intent.json \
  --result-file result.json \
  --policy-eval-id eval_demo \
  --decision-id dec_demo

The CLI automatically manages the action chain head (prevHash). On hash conflicts (concurrent appends), it retries with the server-provided expectedPrevHash.

audit — Audit Operations

# Export a full audit bundle
agentos audit export \
  --from 2026-01-01T00:00:00Z \
  --to 2026-12-31T23:59:59Z \
  --out bundle.json

# Verify bundle integrity offline
agentos audit verify --in bundle.json

# Verify an audit anchor
agentos audit verify-anchor --anchor-file anchor.json

federation — Cross-Tenant Federation

# Prepare a memory export bundle
agentos federation prepare-export \
  --namespace-id ns_demo \
  --key-id fed_key \
  --name demo-bundle \
  --include-links \
  --out prepared.json

# Sign and finalize the export
agentos federation finalize-export \
  --key-id fed_key \
  --name demo-bundle \
  --bundle-hash <hash> \
  --payload payload.json

# Import a foreign bundle
agentos federation import \
  --source-tenant-id tenant_other \
  --bundle-id <bundleId> \
  --payload payload.json \
  --bundle-hash <hash> \
  --signature <sig> \
  --key-public-key "$FED_PUB" \
  --trust-mode capped

demo — Demo Helpers

# Run the full end-to-end demo
# (identity → memory → policy → decision → action → audit)
agentos demo run

# Seed demo data into a running server
agentos demo seed

State Management

The CLI persists context between commands in .agentos/state.json:

{
  "tenantId": "tenant_demo",
  "agentId": "ag_...",
  "versionId": "ver_...",
  "keyId": "key_...",
  "actionChainHead": "abc123...",
  "namespaceId": "ns_...",
  "policyId": "pol_..."
}

This means after running agent register, subsequent commands like memory write automatically use the registered agent's credentials without needing to pass --agent-id again.

Example Workflow

# Start from scratch
agentos keygen --out ./keys

# Register agent
agentos --base-url http://localhost:3000 --tenant-id acme \
  agent register --name my-agent --artifact-hash sha256:abc --semver 1.0.0

# Create namespace and write memory
agentos --tenant-id acme namespace create --name ops --visibility tenant
agentos --tenant-id acme memory write --namespace-id ns_ops --type semantic --content "Production uses us-east-1"

# Query memory
agentos --tenant-id acme memory query --task-type planning --query "which region" --topk 5

# Export audit trail
agentos --tenant-id acme audit export --from 2026-01-01T00:00:00Z --to 2026-12-31T23:59:59Z --out audit.json
agentos audit verify --in audit.json

Part of AgentOS

This CLI is part of the AgentOS platform — an operating layer for autonomous AI agents providing cryptographic identity, governed policy evaluation, tamper-evident audit trails, namespaced semantic memory, and cross-tenant knowledge federation.

License

MIT