npm package: @rayenbenabdallah/agentos-cli
Description: CLI for AgentOS — agent management, memory, policy, audit, and federation
Latest version: 1.0.2

# @rayenbenabdallah/agentos-cli

CLI for [AgentOS](https://github.com/rayenbenabdallah/agentos) — agent management, memory, policy, audit, and federation.

[![npm version](https://img.shields.io/npm/v/@rayenbenabdallah/agentos-cli)](https://www.npmjs.com/package/@rayenbenabdallah/agentos-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

---

## 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

```bash
npm install -g @rayenbenabdallah/agentos-cli
# or
pnpm add -g @rayenbenabdallah/agentos-cli
```

After installation, the `agentos` command is available globally.

---

## Quick Start

```bash
# 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

```bash
agentos keygen --out ./keys
# Writes public.key and private.key to ./keys/
```

### `doctor` — Health Check

```bash
agentos doctor
# AgentOS Health Check
#   API: OK
#   Database: OK
#   Redis: OK
#   Signing: OK
```

### `agent` — Agent Operations

```bash
# 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

```bash
# Create a namespace
agentos namespace create --name support --visibility tenant

# List namespaces
agentos namespace list
```

### `memory` — Memory Operations

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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`:

```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

```bash
# 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](https://github.com/rayenbenabdallah/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](./LICENSE)