Quick Start

Installation

Install the ctx CLI directly from source using Go:

go install github.com/contextsubstrate/ctx/cmd/ctx@latest

Ensure your $GOPATH/bin is in your system PATH to run the command from any directory.

1. Initialize your Store

Navigate to your AI project's root directory and initialize the .ctx substrate. This creates a local content-addressed store for your execution logs and artifacts.

ctx init

This command creates a .ctx/ directory to manage your immutable objects, packs, and configuration.

2. Capture an Execution

ctx transforms standard JSON execution logs into immutable, content-addressed Context Packs.

Assume you have an execution.json produced by your agent. To pack it into the substrate:

ctx pack execution.json

Output:

ctx://8f3a2b1c9d...

The command returns a unique ctx:// URI (a hash of the manifest) that serves as a permanent reference to this specific execution state.

3. Inspect and Trace

Once a pack is created, you can inspect its contents—including the model parameters, system prompts, and tool-calling sequences—without needing the original log file.

# List all captured packs
ctx log

# View the details of a specific pack
ctx show <hash>

4. Debug Drift and Replay

The power of ContextSubstrate lies in its ability to compare executions and replay steps to identify non-deterministic behavior.

Compare Executions

If an agent's behavior changes between versions, use diff to generate a drift report. This identifies changes in prompts, tool parameters, or reasoning steps.

ctx diff <hash-a> <hash-b> --human

Replay Steps

To validate that an execution is reproducible, use the replay command. ctx will attempt to re-execute the steps recorded in the pack to check for fidelity.

ctx replay <hash>

Summary of Basic Commands