@archyai/cli

The Archy command-line tool. Wraps Archy's local-mode primitives — deterministic indexing, MCP server, transparency receipts, and a commit gate — behind one ergonomic archy binary.

Everything in this package runs locally. No cloud credentials. No network calls. No API keys.

Install

# global
npm install -g @archyai/cli

# one-off
npx -y @archyai/cli --help

Node 20 or newer is required.

Subcommands

archy <subcommand> [options]

  index         Populate a local SQLite MCP store from a workspace.
  serve         Boot the MCP server in local mode against a SQLite store.
  audit-self    Run Archy and emit a transparency receipt.
  pre-commit    Block a commit when new critical findings appear on staged files.
  help          Show usage, or `archy help <subcommand>`.

Flags:
  --version, -v   Print the CLI version and exit.
  --help,    -h   Show usage.

archy index

Run Archy's deterministic analysis against a workspace and write the plane data into a local SQLite store. The MCP server reads from that store at runtime, so this is the prerequisite step before archy serve.

archy index --workspace /path/to/repo --db /path/to/.archy/local.db

Options:

• --workspace <path> — workspace to analyze (default: current directory).
• --db <path> — SQLite store path (default: ./.archy/local.db).
• --help, -h — show usage.

Idempotent. Re-running on the same workspace overwrites that workspace's plane rows. Multiple workspaces can share one SQLite file; each is keyed by sha256(absolute path).

archy serve

Boot the Archy MCP server in local mode against a SQLite store.

archy serve --db /path/to/.archy/local.db

Options:

• --db <path> — SQLite store path (default: ./.archy/local.db).
• --workspace-id <id> — pin the server to a specific workspace id (default: derive from the current directory).
• --workspace <path> — alternative to --workspace-id; the server derives the id from this path.
• --help, -h — show usage.

The server speaks MCP over stdio. Wire it into your agent runner's config file as below.

.mcp.json snippet

Drop this into your agent runner's MCP config (Claude Code, Cursor, Continue, Cline, Codex, custom). It runs archy serve via npx against a local SQLite store. No cloud credentials are referenced or required.

{
  "mcpServers": {
    "archy": {
      "command": "npx",
      "args": [
        "-y",
        "@archyai/cli",
        "serve",
        "--db",
        "/absolute/path/to/your/repo/.archy/local.db"
      ]
    }
  }
}

If you already installed the CLI globally, swap the command:

{
  "mcpServers": {
    "archy": {
      "command": "archy",
      "args": [
        "serve",
        "--db",
        "/absolute/path/to/your/repo/.archy/local.db"
      ]
    }
  }
}

Workflow:

1. archy index --workspace . --db .archy/local.db once per code change (or wire it into a post-commit hook).
2. archy serve runs continuously inside your agent runner.

archy audit-self

Run Archy's deterministic analysis against a workspace and write a bounded transparency receipt to disk. Useful for verifying which detectors actually ran on your code, which were blocked, and which findings came back — all without leaking source content.

archy audit-self --workspace . --out ./archy-audit-receipt.json

Options:

• --workspace <path> — workspace to analyze (default: current directory).
• --out <path> — receipt output path (default: ./archy-audit-receipt.json).
• --help, -h — show usage.

The receipt is bounded by design: no raw evidence bodies, no source excerpts, no recommendation prose. It is safe to share with a security team.

archy pre-commit

Block a commit when new critical findings appear on staged files, relative to the workspace's last receipt at .archy/last-receipt.json.

archy pre-commit

Options:

• --workspace <path> — workspace to analyze (default: current directory).
• --help, -h — show usage.

Exit codes:

• 0 — no new criticals on staged files; receipt baseline updated.
• 1 — user error (not a git repo, missing workspace).
• 2 — internal error.
• 3 — new criticals detected; commit blocked.

Wire as a git pre-commit hook:

# .git/hooks/pre-commit
#!/bin/sh
exec archy pre-commit

Or via husky:

npx husky add .husky/pre-commit "archy pre-commit"

After fixing the flagged criticals, refresh the baseline:

archy audit-self --out .archy/last-receipt.json

Exit codes

| Code | Meaning | | ---- | ------- | | 0 | Success | | 1 | User error (bad args, file not found, not a git repo) | | 2 | Internal error | | 3 | archy pre-commit gate failed (new criticals on staged files) |

License

Apache-2.0. Copyright 2026 Archy AI. See LICENSE at the repository root.