Capsula

[!WARNING] This project is in early development. The CLI interface and configuration format may change in future releases.

A powerful CLI tool for capturing and preserving the context of your command executions. Capsula automatically records the state of your project environment before and after running commands, making your workflows reproducible and auditable.

Features

• 📸 Context Capture: Automatically capture git state, file contents, environment variables, and more
• 🔄 Reproducible Runs: Complete record of execution context for debugging and auditing
• 🛡️ Safety Checks: Prevent execution on dirty repositories or other unsafe conditions
• 📊 Structured Output: JSON-formatted capture data for easy processing
• 🔧 Extensible: Multiple built-in context types with clean error handling

Installation

Install from crates.io

cargo install capsula-cli --locked

Install from the GitHub repository

cargo install --git https://github.com/shunichironomura/capsula --branch rust --locked capsula-cli

Quick Start

1. Create a configuration file (capsula.toml) in your project root:

[vault]
name = "my-project"

[[phase.pre.contexts]]
type = "git"
name = "repo-name"
path = "."

[[phase.pre.contexts]]
type = "cwd"

[[phase.pre.contexts]]
type = "file"
glob = "config.json"
mode = "copy"
hash = "sha256"

2. Run a command with context capture:

capsula run python train_model.py

3. Or capture context only:

capsula capture --phase pre

Configuration

Basic Structure

The capsula.toml configuration file defines:

• Vault: Where to store captured data
• Phases: When to capture context (before/after command execution)
• Contexts: What information to capture

[vault]
name = "project-name"        # Vault identifier
path = ".capsula"           # Storage path (optional, defaults to .capsula/{name})

[phase.pre]                 # Pre-execution contexts
[[phase.pre.contexts]]
type = "git"
# ... context configuration

[phase.post]                # Post-execution contexts
[[phase.post.contexts]]
type = "file"
# ... context configuration

Available Context Types

Git Context

Captures git repository state including commit hash and cleanliness check.

[[phase.pre.contexts]]
type = "git"
name = "repo-name"          # Context name
path = "."                  # Repository path
allow_dirty = false         # Allow uncommitted changes (default: false)

Output Example:

{
  "__meta": { "success": true, "index": 0 },
  "type": "git",
  "name": "repo-name",
  "working_dir": "/path/to/repo",
  "sha": "abc123...",
  "is_dirty": false,
  "abort_on_dirty": false
}

Current Working Directory Context

Captures the current working directory path.

[[phase.pre.contexts]]
type = "cwd"

Output Example:

{
  "__meta": { "success": true, "index": 1 },
  "type": "cwd",
  "cwd": "/current/working/directory"
}

File Context

Captures file contents and/or metadata.

[[phase.pre.contexts]]
type = "file"
glob = "config.json"        # File pattern to capture
mode = "copy"               # Capture mode ("copy", "move", or "none". default: "copy")
hash = "sha256"             # Calculate file hash ("sha256" or "none". default: "sha256")

Output Example:

{
  "__meta": { "success": true, "index": 2 },
  "type": "file",
  "files": [
    {
      "path": "/path/to/config.json",
      "copied_path": "/vault/run-dir/config.json",
      "hash": "sha256:abc123..."
    }
  ]
}

Note: Copy and move modes require a run directory and only work during capsula run command, not standalone capsula capture.

Environment Variables Context

Captures specified environment variables.

[[phase.pre.contexts]]
type = "env"
name = "HOME"                 # Variable name to capture

Output Example:

{
  "__meta": { "success": true, "index": 3 },
  "type": "env",
  "name": "HOME",
  "value": "/home/user"
}

Command Context

Captures output of shell commands.

[[phase.pre.contexts]]
type = "command"
command = ["uname", "-a"]
abort_on_failure  = false  # Abort if command fails (default: false)

Machine Context

Captures system information like CPU, memory, and OS details.

[[phase.pre.contexts]]
type = "machine"

CLI Usage

Commands

capsula run <command>

Execute a command with full context capture.

# Run with default config
capsula run python script.py

# Run with custom config
capsula run --config my-config.toml python script.py

# Run with arguments
capsula run python train.py --epochs 100 --lr 0.01

Behavior:

1. Captures pre-phase contexts and saves to vault
2. Checks for abort conditions (e.g., dirty git repo)
3. Executes the command if safe, aborts otherwise
4. Captures post-phase contexts and saves to vault

capsula capture

Capture context without running a command.

# Capture pre-phase contexts
capsula capture --phase pre

# Capture post-phase contexts
capsula capture --phase post

Options

• --config <path>: Specify custom configuration file (default: capsula.toml)
• --phase <phase>: Specify phase for capture command (pre or post)

Output Structure

Metadata

Every context output includes metadata for traceability:

{
  "__meta": {
    "success": true, // Capture success status
    "index": 0 // Position in configuration (0-based)
  }
  // ... context-specific data
}

Vault Structure

Captured data is organized in the vault:

.capsula/
└── vault-name/
    └── 2024-01-15/ # Date-based directory (YYYY-MM-DD, UTC)
        └── 143022-example-run--01HKJM2K3L4M5N6P7Q8R9S/ # Unique run directory (timestamp + run name + ULID)
            ├── metadata.json    # Run metadata
            ├── pre.json        # Pre-phase contexts
            ├── run.json        # Command output, exit code, duration
            └── post.json       # Post-phase contexts