CLI Reference | d3cipher Documentation

Overview

LockStock ships two Docker images. Between them, three CLI tools:

CLI	Image	Runs on	Purpose
`lockstock-gateway`	admin-tools	Your host machine	Manage agents, start/stop the gateway container
`lockstock-audit`	admin-tools	Inside the container	Decrypt and export agent transcripts
`lockstock-rotate`	admin-tools	Inside the container	Rotate your Account Key (re-wrap encryption keys)

The gateway image contains no CLIs — it is the service container, managed by lockstock-gateway.

Extract the gateway CLI to your host

mkdir -p ~/.local/bin
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 \
  cat /usr/local/bin/lockstock-gateway > ~/.local/bin/lockstock-gateway && \
  chmod +x ~/.local/bin/lockstock-gateway

Command not found after extraction? Run: export PATH="$HOME/.local/bin:$PATH"

Run audit and rotate inside the container

# These run inside the admin-tools container — no extraction needed
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 \
  lockstock-audit --help

docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 \
  lockstock-rotate --help

lockstock-gateway

Manages agent identities and the gateway Docker container. Reads all configuration from Liberty automatically. Runs on your host machine, not inside a container.

provision

Create and activate a new agent in one command. Provisions on the server, burns the genesis token, and writes the agent ID to Liberty.

lockstock-gateway provision --name my-agent [--provider TYPE] [--tasks LIST]

Flag	Required	Description
`--name`	required	Agent name. Becomes the Liberty key suffix: `LOCKSTOCK_AGENT_MY_AGENT`
`--provider`	optional	AI provider type: `anthropic-native` or `openai`. Auto-detected from which provider key is in Liberty (Anthropic key present → `anthropic-native`, otherwise → `openai`).
`--tasks`	optional	Comma-separated capabilities. Default: `all`. Options: `CHATCOMPLETION`, `COMPLETION`, `EMBEDDING`, `IMAGEGENERATION`, `TRANSCRIPTION`, `TEXTTOSPEECH`, `FILEREAD`, `FILEWRITE`, `SHELL`, `NETWORK`, `DATABASE`, `DEPLOY`, `RESTART`, `BACKUP`, `FREEZE`, `EXPORT`, `DELEGATE`, `HANDOFF`. `HEARTBEAT` and `CHECKPOINT` are always included.

Example

# Full access (default)
lockstock-gateway provision --name claude-dev

# Least-privilege: only chat completion and embedding
lockstock-gateway provision --name claude-prod --tasks CHATCOMPLETION,EMBEDDING

# Explicit provider override
lockstock-gateway provision --name gpt-agent --provider openai

Dashboard equivalent: Provision Agent button. The dashboard lets you pick capabilities from a checklist.

activate

Burn a genesis token created from the dashboard. This is the second half of the dashboard provisioning path: provision in the dashboard, activate on the host.

lockstock-gateway activate --agent ID --token TOKEN [--name LABEL] [--provider TYPE]

Flag	Required	Description
`--agent`	required	Agent ID from the dashboard (e.g., `agent_XXXXXXXX_my_agent`)
`--token`	required	Genesis token from the dashboard. Single-use. Expires in 24 hours.
`--name`	optional	Liberty key label. If omitted, derived from the agent ID (e.g., `agent_44ebd9c5_myagent` → `LOCKSTOCK_AGENT_MYAGENT`).
`--provider`	optional	Same as `provision --provider`. Auto-detected if omitted.

Genesis tokens are single-use and expire in 24 hours. If yours has expired, provision a new agent from the dashboard.

agents

List all agents registered in your Liberty vault, with their chain depth (sequence number).

lockstock-gateway agents

Example output

=== Registered Agents ===

  MY_AGENT    agent_a3f7b2c1_my_agent  (seq=42)
    liberty show LOCKSTOCK_AGENT_MY_AGENT

Dashboard equivalent: Fleet tab — shows all agents, chain depth, status, and kill switch.

setup

Generate gateway-wide infrastructure. Currently generates LOCKSTOCK_MLS_SEED (Layer 5 agent-to-agent E2EE). Idempotent — safe to run multiple times.

lockstock-gateway setup

Only requires Liberty to be installed. No API key, no agents, no server connection needed. Runs automatically during provision and activate, so most customers never need to call it explicitly.

No dashboard equivalent — terminal only.

start

Start the gateway Docker container. Reads all configuration from Liberty, creates a temporary env file, starts the container with --network host (binds 127.0.0.1:4000), and shreds the env file.

lockstock-gateway start

Requires LOCKSTOCK_API_KEY and LOCKSTOCK_UPSTREAM_URL in Liberty. At least one agent must be registered. For single-agent deployments, auto-sets AGENT_ID on the container. Warns if MLS_SEED is missing (run setup or provision first).

No dashboard equivalent — terminal only.

stop

Stop and remove the gateway container.

lockstock-gateway stop

No dashboard equivalent — terminal only.

status

Show container state (running/stopped + uptime), all registered agents with chain depth, and full Liberty configuration. The single most useful debugging command.

lockstock-gateway status

Dashboard equivalent: Fleet tab (agents only — no container state or config).

config

Show all Liberty configuration keys with their status: set (masked), MISSING (required), NOT SET (optional), or default value. Use this to verify your setup before running start.

lockstock-gateway config

Example output

=== Gateway Configuration ===

  LOCKSTOCK_API_KEY              lsk_admi...xyz1
  LOCKSTOCK_GATEWAY_KEY          lsk_gate...abc2
  LOCKSTOCK_ACCOUNT_KEY          85d7a50b...9f3e
  LOCKSTOCK_URL                  (default: https://api.d3cipher.ai)
  LOCKSTOCK_UPSTREAM_URL         https://...thro
  LOCKSTOCK_PORT                 (default: 4000)
  ANTHROPIC_API_KEY              sk-ant-a...k8z2
  OPENAI_API_KEY                 (not set)

No dashboard equivalent — terminal only.

lockstock-audit

Decrypt agent conversation transcripts from the LockStock chain. Runs inside the admin-tools container. The server never sees plaintext — decryption happens locally using your Account Key.

Compliance officers: The dashboard Auditor tab does the same thing with a point-and-click interface. Select an agent, enter your Account Key, and browse transcripts. No Docker or terminal needed.

The CLI exists for bulk export, sequence range queries, CI/CD pipeline integration, and air-gapped environments where the dashboard isn't available.

docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 \
  lockstock-audit \
    --account-key "your-64-char-hex-key" \
    --agent-id "agent_XXXXXXXX_name" \
    --api-key "lsk_admin_..." \
    [--limit 50] \
    [--from-seq 100] [--to-seq 200] \
    [--format text|json] \
    [--raw] \
    [--server-url URL]

Flag	Required	Description
`--account-key`	required	Your Account Key as a 64-character hex string (32 bytes). Generated in the dashboard (Step 5 of the Quickstart).
`--agent-id`	required	Agent ID to audit (e.g., `agent_a3f7b2c1_my_agent`). Find it with `lockstock-gateway agents` or in the dashboard Fleet tab.
`--api-key`	required	Your Admin Key (`lsk_admin_*`). The Gateway Key does not have audit permissions.
`--limit`	optional	Maximum number of audit entries to fetch. Default: 50. Set higher for bulk exports (e.g., `--limit 10000`).
`--from-seq`	optional	Start from this sequence number (inclusive). Use with `--to-seq` for targeted compliance pulls.
`--to-seq`	optional	End at this sequence number (inclusive).
`--format`	optional	`text` (default, structured audit records with all fields) or `json` (machine-readable, for scripting and CI/CD).
`--raw`	optional	Output the exact canonical bytes (bencode) that hash to `payload_hash`. For independent chain verification: pipe to `sha256sum` and compare against the chain entry. Metadata goes to stderr, canonical bytes to stdout.
`--server-url`	optional	Override the d3cipher cloud URL. Only needed for on-premise deployments.

Examples

# Read the last 50 transcripts (human-readable)
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-audit \
  --account-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --agent-id "$(liberty show LOCKSTOCK_AGENT_MY_AGENT)" \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)"

# Bulk export to JSON file
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-audit \
  --account-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --agent-id "$(liberty show LOCKSTOCK_AGENT_MY_AGENT)" \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)" \
  --limit 10000 --format json > audit-export.json

# Targeted range (e.g., "what happened between sequence 500 and 600?")
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-audit \
  --account-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --agent-id "$(liberty show LOCKSTOCK_AGENT_MY_AGENT)" \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)" \
  --from-seq 500 --to-seq 600

# Independent chain verification — prove a specific entry hasn't been tampered with
# SHA-256 of the raw output should match the entry's payload_hash
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-audit \
  --account-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --agent-id "$(liberty show LOCKSTOCK_AGENT_MY_AGENT)" \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)" \
  --from-seq 500 --to-seq 500 --raw | sha256sum
# → a1b2c3d4...  (compare this to payload_hash in the audit log)

lockstock-rotate

Rotate your Account Key — re-wrap all agent DEKs (data encryption keys) under a new key. Runs inside the admin-tools container. The server never sees the plaintext DEK during rotation.

No dashboard equivalent yet. Key rotation is currently CLI-only. Use --dry-run first to preview what will change, then run without --dry-run to execute.

docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 \
  lockstock-rotate \
    --old-key "current-64-char-hex-key" \
    --new-key "new-64-char-hex-key" \
    --api-key "lsk_admin_..." \
    [--dry-run] \
    [--generate-key] \
    [--format text|json] \
    [--server-url URL]

Flag	Required	Description
`--old-key`	required*	Your current Account Key (64-char hex). Required for rotation (not needed with `--generate-key`).
`--new-key`	required*	The replacement Account Key (64-char hex). Generate one with `--generate-key`.
`--api-key`	required*	Your Admin Key (`lsk_admin_*`).
`--dry-run`	optional	Show what would change without writing to the server. Always run this first.
`--generate-key`	optional	Generate a cryptographically random 64-char hex key and exit. Use this to create the new key before rotating.
`--format`	optional	`text` (default) or `json` (machine-readable).
`--server-url`	optional	Override the d3cipher cloud URL. Only for on-premise deployments.

Examples

# Step 1: Generate a new key
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-rotate --generate-key
# → a1b2c3d4e5f6...  (save this immediately)

# Step 2: Preview the rotation (dry run)
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-rotate \
  --old-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --new-key "a1b2c3d4e5f6..." \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)" \
  --dry-run

# Step 3: Execute the rotation
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-rotate \
  --old-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --new-key "a1b2c3d4e5f6..." \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)"

# Step 4: Update Liberty with the new key
liberty add LOCKSTOCK_ACCOUNT_KEY "a1b2c3d4e5f6..."

# Step 5: Restart the gateway to use the new key
lockstock-gateway stop && lockstock-gateway start

Automation & CI/CD

All three CLIs support --format json for machine-readable output. This enables integration with CI/CD pipelines, monitoring systems, and compliance automation.

Nightly compliance export

# crontab: export all agent transcripts every night at 2am
0 2 * * * docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-audit \
  --account-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --agent-id "$(liberty show LOCKSTOCK_AGENT_PROD)" \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)" \
  --limit 10000 --format json > /var/log/lockstock/audit-$(date +%Y%m%d).json

Quarterly key rotation

# Generate new key, dry-run review, rotate, update Liberty, restart
NEW_KEY=$(docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-rotate --generate-key)
echo "New key: $NEW_KEY"

docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-rotate \
  --old-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --new-key "$NEW_KEY" \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)" \
  --dry-run

# Review output, then execute:
docker run --rm registry.gitlab.com/d3cipher/lockstock-images/admin-tools:v4.19.2 lockstock-rotate \
  --old-key "$(liberty show LOCKSTOCK_ACCOUNT_KEY)" \
  --new-key "$NEW_KEY" \
  --api-key "$(liberty show LOCKSTOCK_API_KEY)"

liberty add LOCKSTOCK_ACCOUNT_KEY "$NEW_KEY"
lockstock-gateway stop && lockstock-gateway start

Health monitoring

# Parse gateway health as JSON
curl -s http://localhost:4000/healthz | jq .

# Prometheus metrics endpoint
curl -s http://localhost:4000/metrics

Infrastructure as code

# Provision agents in a shell script or Ansible playbook
for agent in analyst researcher reviewer; do
  lockstock-gateway provision --name "$agent" --tasks CHATCOMPLETION,EMBEDDING
done
lockstock-gateway agents

Troubleshooting

Error	Cause	Fix
`lockstock-gateway: command not found`	CLI not extracted or not in PATH	Extract from admin-tools (see above). Add `~/.local/bin` to PATH.
`liberty CLI not found`	Liberty not installed	`pipx install liberty-secrets && liberty init`
`LOCKSTOCK_API_KEY not in Liberty vault`	Keys not stored yet	`liberty add LOCKSTOCK_API_KEY "lsk_admin_..."`
`No agents in Liberty vault`	No agents provisioned	`lockstock-gateway provision --name my-agent`
`Claim failed. Genesis token may have expired`	Token older than 24 hours or already used	Provision a new agent from the dashboard. Tokens are single-use.
`Gateway failed to start`	Container crashed	`docker logs d3cipher-gateway` for details. Common: wrong upstream URL.
`/healthz returns 503`	Can't reach d3cipher cloud	Check network connectivity. Check `LOCKSTOCK_URL` if set.

Next Steps

Gateway Quickstart — step-by-step setup guide
Compliance Quickstart — governance policies and audit workflows
API Reference — REST endpoints for fleet management and provisioning
Open Dashboard — manage agents, set budgets, audit transcripts
Liberty Docs — hardware-bound secrets manager