@agledger/cli

The official CLI for the AGLedger API — accountability infrastructure for AI agents. The Layer 3 accountability layer of the agent stack.

A thin cover over the API. The CLI passes your request straight through to the API and forwards the response — no hand-coded per-endpoint wrappers, no flag-to-body translation, no drift. Every AGLedger API route is reachable via agledger api <METHOD> <path>.

Learn more

• agledger.ai — what AGLedger is and why Layer 3 accountability matters
• How it works — the four-endpoint lifecycle: record, completion, verdict, fulfill
• Glossary — canonical definitions of Record, Completion, SCITT Receipt, Verdict, Settlement Signal
• API reference — every endpoint the CLI covers
• Documentation — installation and integration guides

Install

npm install -g @agledger/cli

Quick Start

export AGLEDGER_API_KEY=agl_adm_...
export AGLEDGER_API_URL=https://your-agledger-instance

# Check health, identity, scopes, and get the quickstart workflow
agledger discover

# List Record types
agledger api GET /v1/schemas

# Create a record (raw JSON body). Types are customer-registered; a fresh org
# is seeded with `notarize-generic-v1` (and 3 other editable samples).
# `criteria` is validated against the JSON Schema you registered for the type.
agledger api POST /v1/records --data '{
  "type": "notarize-generic-v1",
  "criteria": { "task_description": "summarize Q3 filings" }
}'

# Or build the body with typed fields
agledger api POST /v1/records \
  -F type=notarize-generic-v1 \
  -F criteria.task_description='summarize Q3 filings'

# Submit a completion. On a gated record the principal then renders a Verdict
# (accept / reject) on the Completion — use the route documented in the API
# (see `agledger api GET /openapi.json`).
agledger api POST /v1/records/<record-id>/completions \
  --data '{"evidence":{"summary":"delivered 500x copper wire","evidenceUrl":"https://orders.example.com/CW-500"}}'

Why a thin cover?

• Zero drift. When the API adds, renames, or removes a route, the CLI keeps working — no code change required.
• One mental model. The API docs are the CLI docs. What you read in the OpenAPI spec is what you type.
• All 250+ routes on day one. You get full parity, not a hand-picked subset.

Ways to pass a body

Flag	When to use
--data '{...}'	Agent-friendly: one JSON string
--input file.json	Complex payloads; reuse files
--input -	Pipe JSON from stdin
-F key=value (repeatable)	Shell-friendly; typed (true/false/null/numbers); nested via a.b=v; arrays via arr[]=v; JSON literals via k={...} / k=[...]

Merging order (low → high): --data → --input → -F → --query. Later sources override earlier keys.

Agent-native DX

• --json on every command (auto when stdout is piped)
• --quiet suppresses output (exit code only)
• --dry-run on agledger api shows the request without sending
• --paginate on GET follows cursor pagination and streams NDJSON
• Structured errors on stderr: {error: true, code, message, suggestion, ...} — API errors pass through verbatim
• Semantic exit codes: 0 (OK), 2 (usage), 3 (auth), 4 (forbidden), 5 (not found), 6 (conflict), 7 (rate limit), 8 (server), 9 (network), 10 (timeout)
• NO_COLOR supported per no-color.org

Discovery

agledger list-commands --json          # 10 CLI-local commands
agledger help-json api --json          # Schema for `api` (args + flags)
agledger discover                       # Health + identity + quickstart
agledger api GET /openapi.json          # Full API route catalog

CLI-local commands (everything else is agledger api)

Command	Purpose
api	Call any API endpoint
discover	Health + identity + scopes + quickstart
login	Verify API key, store in ~/.agledger/config.json (0600)
logout	Remove profile(s)
auth	Check current login state (exit 0 either way)
config	list / get / use <profile> / path
verify	Offline audit export verification (COSE_Sign1 + Ed25519, RFC 9052, no network)
docs	Fetch the API's agent-oriented narrative (llms.txt / --full)
list-commands	Inventory (this list)
help-json	Per-command schema

Authentication

# Verifies the key against the API, then stores it under ~/.agledger/config.json (0600)
agledger login --api-key agl_adm_... --profile prod

# Switch the active profile — subsequent commands use its key automatically
agledger config use prod

# Run a one-off against a specific stored profile
agledger api GET /v1/records --profile prod

# Or pass credentials per-invocation via env or flags (no stored profile needed)
AGLEDGER_API_KEY=... AGLEDGER_API_URL=... agledger api GET /v1/records

Credential precedence (highest first) — applied per command:

• API key: --api-key flag → AGLEDGER_API_KEY env → stored profile (--profile <name>, else the active profile).
• API URL: --api-url flag → AGLEDGER_API_URL env → stored profile URL → default.

So once you agledger login, plain agledger api ... calls authenticate from the stored profile with no flags or env. --dry-run echoes the resolved auth (URL, source, masked key) so you can confirm which credentials a call would use without sending it.

Agent keys (agl_agt_*) and admin keys (agl_adm_*) are both accepted — the API routes them appropriately.

Requirements

• Node.js >= 24.0.0
• A running AGLedger API instance

License

Proprietary. Copyright (c) 2026 AGLedger LLC. All rights reserved. See LICENSE.