CLI Reference Guide

The ctx command-line interface is the primary tool for interacting with the ContextSubstrate execution substrate. It provides a developer-native workflow for managing the lifecycle of AI agent executions—from capture and storage to re-execution and drift analysis.

Global Flags

These flags are available on all ctx commands:

| Flag | Shorthand | Description | | :--- | :--- | :--- | | --verbose | -v | Enable verbose/debug output for troubleshooting. | | --version | | Display the current version, commit hash, and build date. | | --help | -h | Display help information for any command. |

Command Reference

ctx init

Initializes a new context store in the current working directory.

This command creates a .ctx/ directory structure used to store immutable objects, packs, and references. It is the first command you should run when starting a new project.

Usage:

ctx init

ctx pack

Creates an immutable, content-addressed Context Pack from an agent execution log.

The command reads a JSON-formatted execution log, stores all inputs, prompts, and outputs as blobs, and generates a unique hash (identity) for the execution.

Usage:

ctx pack <log-file.json>

Output: Returns a ctx://<hash> URI which serves as the unique identifier for that execution.

ctx show

Inspects the contents of a specific context pack.

Displays a human-readable summary including the model used, system prompts, input files, execution steps (tool calls), and final output artifacts.

Usage:

ctx show <hash>

Arguments:

• <hash>: The full hash, a short hex prefix, or a ctx:// URI.

ctx log

Lists all finalized context packs stored in the local substrate.

Packs are displayed in reverse chronological order (most recent first). This is useful for finding hashes of previous runs for comparison or replaying.

Usage:

ctx log

ctx diff

Compares two context packs to identify "drift"—differences in prompts, tool parameters, or reasoning.

By default, diff produces a structured JSON report suitable for programmatic analysis. Use the --human flag for a readable summary of differences.

Usage:

ctx diff <hash-a> <hash-b> [flags]

Flags:

• --human: Output a human-readable summary instead of raw JSON.

Detected Drift Types:

• prompt_drift: Differences in system or user prompts.
• tool_drift: Differences in which tools were called or the order of calls.
• param_drift: The same tool was called but with different input parameters.
• reasoning_drift: The tool produced different output despite having the same inputs.

ctx replay

Re-executes a recorded agent run step-by-step.

The command attempts to reproduce the execution captured in the pack. It reports on "fidelity"—how closely the new execution matches the original.

Usage:

ctx replay <hash>

Exit Codes:

• 0: Success / High Fidelity.
• 1: Degraded Fidelity (outputs diverged but execution completed).
• 2: Execution Failed.

ctx verify

Validates the provenance of a specific artifact.

Checks an artifact's metadata against the context store to ensure it was actually produced by the recorded agent execution and has not been tampered with.

Usage:

ctx verify <path-to-artifact>

ctx fork

Creates a mutable draft derived from an existing context pack.

This allows you to take an existing execution, modify the prompts or inputs in the resulting draft directory, and then re-pack it to create a new branch of execution.

Usage:

ctx fork <hash>

Workflow:

1. Fork a pack.
2. Edit the files in the reported draft path.
3. Use ctx pack on the modified draft to finalize.

ctx completion

Generates shell completion scripts.

Usage:

ctx completion [bash|zsh|fish|powershell]

To load completions in your current shell:

source <(ctx completion zsh)

The .ctx Directory

The CLI manages a hidden directory in your project root. While you should generally interact with it via the CLI, it contains:

• objects/: Content-addressed blobs of all data.
• packs/: The index of finalized execution manifests.
• config.json: Local store configuration.