Welcome to Capsula¶

Capsula is a command-line tool that automatically captures and saves information about your command executions. It records what happened, when it happened, and the environment in which it happened.

What Does Capsula Do?¶

When you run a command with Capsula, it:

1. Records the environment - Captures git state, environment variables, file contents, and system information
2. Runs your command - Executes your command normally, capturing its output
3. Saves everything - Stores all captured data in an organized directory structure

Quick Example¶

Create a capsula.toml file:

[vault]
name = "my-project"

[[pre-run.hooks]]
id = "capture-git-repo"
path = "."

[[post-run.hooks]]
id = "capture-file"
glob = "output.txt"
mode = "copy"

Run your command:

capsula run python train_model.py

Capsula creates an organized directory:

.capsula/my-project/2025-01-09/143022-happy-river/
├── _capsula/
│   ├── metadata.json      # What ran, when, and where
│   ├── pre-run.json       # Environment before
│   ├── command.json       # Command output
│   └── post-run.json      # Results after
└── output.txt             # Your output file

Why Use Capsula?¶

• Reproducibility - Capture the exact environment and inputs for every run
• Traceability - Know which code version produced which results
• Auditing - Generate complete execution records
• Debugging - Understand what went wrong by reviewing the complete context

Getting Started¶