CLI

The AGLedger CLI is a command-line interface for your AGLedger instance. It serves two audiences: developers scripting against the API, and AI agents that need a tool interface without the MCP protocol.

Why it matters

Not every agent speaks MCP. Some agents work through shell commands, CI/CD pipelines invoke accountability steps as build stages, and developers need to inspect mandates from a terminal. The CLI covers all of these with a single binary that outputs structured JSON when piped and human-readable tables when interactive.

For AI agents specifically, the CLI is designed to be self-discoverable. An agent can learn every available command, inspect the schema for any command, and execute it — all without documentation or human guidance.

Prerequisites

Before setting up the CLI, you need:

  1. A running AGLedger instance — See the Installation guide if you haven't deployed yet
  2. An API key — Either an agent key (ach_age_*) or enterprise key (ach_ent_*), created during self-hosted onboarding

Agent keys are appropriate when the CLI is used by or on behalf of an AI agent. Enterprise keys are appropriate for admin scripts, CI/CD pipelines, and human operators. See Scope Profiles for the permissions each key type provides.

When creating keys, set the label field to identify the key's purpose in audit trails (e.g., "deploy-pipeline-prod" or "data-agent-cli"). For agent accounts, set orgUnit and description to trace activity back to a team. See the MCP Server guide for the full list of metadata fields.

Install

npm install -g @agledger/cli

Requires Node.js 22 or later.

Connect to your AGLedger instance

# Set your API key and instance URL
export AGLEDGER_API_KEY=ach_age_your_key
export AGLEDGER_API_URL=http://10.0.1.50:3001

# Verify the connection
agledger status

You can also pass credentials per-command:

agledger status --api-key ach_age_your_key --api-url http://10.0.1.50:3001

Network requirements

The CLI runs on the same machine as the user or agent. It connects outbound to your AGLedger API server on the configured port. No inbound ports are required.

The accountability workflow

Every AGLedger interaction follows the same pattern. The CLI maps each step to a command:

# 1. Discover what contract types are available
agledger schema list

# 2. Inspect the schema for your contract type
agledger schema get ACH-DATA-v1

# 3. Create a mandate (the commitment)
agledger mandate create \
  --type ACH-DATA-v1 \
  --data '{"criteria":{"dataset":"quarterly-sales","format":"csv","row_count_min":1000}}'

# 4. Do your work...

# 5. Submit a receipt (the evidence)
agledger receipt submit MANDATE_ID \
  --data '{"evidence":{"dataset":"quarterly-sales","format":"csv","row_count":1247}}'

# 6. Record the outcome (principal's verdict)
agledger verdict render MANDATE_ID PASS --reason "Data delivered within tolerance"

Previewing before committing

Every mutating command supports --dry-run, which shows what would be sent to the API without sending it:

agledger mandate create --type ACH-PROC-v1 --data '{"criteria":{...}}' --dry-run

Agent integration

How agents discover commands

The CLI provides three levels of discovery, each more detailed than the last:

Level 1: SKILL.md (~50 tokens)

A plain text file installed with the CLI that gives agents the workflow pattern and key commands. This is the cheapest way for an agent to learn what the CLI does.

Level 2: Command inventory

agledger list-commands --json

Returns all 54 commands with their descriptions as JSON. An agent can scan this to find the right command for any task.

Level 3: Command schema

agledger help-json "mandate create"

Returns the full argument and flag schema for a single command, including types, defaults, and descriptions. An agent uses this to construct the exact command it needs.

Structured output

When piped or run with --json, every command outputs JSON:

# Interactive: human-readable table
agledger mandate list --status ACTIVE

# Piped or --json: structured JSON
agledger mandate list --status ACTIVE --json

For paginated results, --all streams every page as newline-delimited JSON (NDJSON):

agledger mandate list --status ACTIVE --all > all-mandates.ndjson

Exit codes

Every command returns a semantic exit code that agents can use for control flow:

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Usage error (bad arguments) | | 3 | Authentication error | | 4 | Forbidden (insufficient scopes) | | 5 | Not found | | 6 | Conflict (invalid state transition) | | 7 | Rate limited | | 8 | Server error | | 9 | Network error | | 10 | Timeout |

Error recovery

Every error response includes a suggestion field with a specific next action:

{
  "error": true,
  "code": "NOT_FOUND",
  "message": "Mandate not found",
  "suggestion": "Run \"agledger mandate list\" to see your mandates and verify the ID."
}

Agents read the suggestion and self-correct. This eliminates the common failure pattern where an agent encounters an error and asks the user for help.

CI/CD integration

The CLI is designed for non-interactive environments. It never prompts — if required input is missing, it fails with a structured error and suggestion. This makes it safe for pipelines.

Example: accountability gate in a deployment pipeline

#!/bin/bash
set -e

# Create a mandate for this deployment
MANDATE=$(agledger mandate create \
  --type ACH-INFRA-v1 \
  --activate \
  --data "{\"criteria\":{\"service\":\"$SERVICE_NAME\",\"version\":\"$VERSION\",\"environment\":\"production\"}}" \
  --json)

MANDATE_ID=$(echo "$MANDATE" | jq -r '.id')

# ... run your deployment ...

# Submit the receipt
agledger receipt submit "$MANDATE_ID" \
  --data "{\"evidence\":{\"deployed\":true,\"health_check\":\"passing\",\"rollback_available\":true}}"

Suppressing output

Use --quiet to suppress all output. The command still sets the exit code, so you can use it for conditional logic:

if agledger status --quiet; then
  echo "AGLedger is reachable"
fi

Color control

The CLI respects the NO_COLOR environment variable (no-color.org). Set NO_COLOR=1 in CI environments to disable ANSI color codes.

Customization

Custom SKILL.md

The SKILL.md file is the first thing an agent reads when it encounters the CLI. It ships with a generic workflow, but you can replace it with one tailored to your organization:

# AGLedger CLI

Your company's accountability system. All agent work must be tracked.

## Workflow
1. `agledger schema list` -- our types are ACH-DATA-v1 and ACH-INFRA-v1
2. `agledger schema get <type>` -- check required fields
3. `agledger mandate create --type <type> --data '...'` -- create before starting work
4. `agledger receipt submit <id> --data '...'` -- submit when done

## Discovery
- `agledger list-commands --json` -- see all commands
- `agledger help-json <command>` -- get command schema

By listing your specific contract types in step 1, agents skip the schema discovery step entirely. This reduces token usage and API calls.

The file is located at SKILL.md in the CLI's install directory. You can also provide it separately to your agent's context alongside the CLI tool definition.

Agent key routing

API keys with the ach_age_ prefix are automatically routed to agent-specific endpoints. When an agent creates a mandate with an agent key, the CLI sends the request to POST /v1/mandates/agent instead of POST /v1/mandates, which applies agent-appropriate defaults.

Command reference

The CLI has 54 commands across 10 topics:

| Topic | Commands | Description | |-------|----------|-------------| | mandate | 12 | Create, list, get, accept, reject, cancel, transition, outcome, chain, batch, counter-propose, request-revision | | schema | 16 | List, get, register, validate, preview, diff, template, blank-template, export, import, deprecate, versions, get-version, check-compatibility, rules, meta-schema | | receipt | 3 | Submit, list, get | | verdict | 1 | Render (PASS/FAIL with settlement signal) | | audit | 2 | Trail, events | | webhook | 3 | Create, list, delete | | agent | 2 | List, reputation | | federation | 6 | Health, create-token, list-gateways, revoke-gateway, query-mandates, audit-log | | admin | 3 | Create-enterprise, create-agent, set-config | | Utility | 6 | Status, login, auth, list-commands, help-json, verify-keys |

Run agledger list-commands for the complete inventory, or agledger help-json <command> for the full schema of any command.

Troubleshooting

Agent invents commands that do not exist

The agent is guessing command names instead of discovering them. Ensure the agent has access to SKILL.md or instruct it to run agledger list-commands --json before attempting any other command.

Connection refused or timeout

The CLI cannot reach your AGLedger API. Verify:

"No API key" error

Set AGLEDGER_API_KEY as an environment variable or pass --api-key on every command. The CLI never prompts for credentials interactively.