CLI Reference¶

Complete reference for Capsula command-line interface.

Global Options¶

--config <PATH>¶

Specify a custom configuration file.

capsula --config /path/to/custom.toml run python script.py

Default: Looks for capsula.toml in current directory and parent directories.

--vault-path <PATH>¶

Override the vault path. Can also be set via the CAPSULA_VAULT_PATH environment variable (after dotenv loading).

capsula --vault-path /custom/vault/path list

--version¶

Show Capsula version.

capsula --version

--help¶

Show help information.

capsula --help
capsula run --help

capsula run¶

Execute a command with hook capture.

Usage¶

capsula run <COMMAND> [ARGS...]

Examples¶

capsula run echo "Hello, World!"
capsula run python train.py --epochs 100
capsula run bash -c 'python generate.py | grep result > output.txt'

Environment Variables¶

Your command runs with these environment variables:

Example using environment variables:

capsula run bash -c 'echo "Run: $CAPSULA_RUN_NAME"'

capsula run-start¶

Start a manual run: create the run directory and execute pre-run hooks.

Use this when you want to capture context before and after an external process (e.g., a GUI-triggered analysis) that capsula does not manage directly. The auto-generated run name is printed to stdout so callers can capture it, then later finalize the run with run-end.

Usage¶

capsula run-start

Example¶

# Start a manual run and capture the name
name=$(capsula run-start)

# ... perform your external process ...

# Finalize the run
capsula run-end "$name"

capsula run-end¶

End a manual run: execute post-run hooks for an existing run.

Finalizes a run previously started with run-start. This command will fail if the run has already been finalized (i.e., post-run.json already exists).

Usage¶

capsula run-end <RUN_NAME>

Example¶

capsula run-end happy-river

capsula list¶

List all captured runs.

Usage¶

capsula list

Output Format¶

TIMESTAMP (UTC)      NAME                  COMMAND
---------------------------------------------------------------------------------------------
2025-01-09 14:30:29  happy-river           echo hello
2025-01-09 14:30:28  clever-mountain       python script.py
2025-01-09 14:30:26  quiet-lake            cargo build --release

capsula show¶

Show detailed information about a specific run, including metadata, command result, and hook summaries.

Usage¶

capsula show <RUN_NAME>
capsula show <RUN_NAME> --json

Options¶

Example¶

$ capsula show happy-river
Run:       happy-river
ID:        01K8WSYC91YAE21R7CWHQ4KYN2
Timestamp: 2025-01-09 14:30:22 UTC
Command:   python train.py --epochs 100
Directory: /path/.capsula/vault/2025-01-09/143022-happy-river
Result:    exit 0 (1.23s)

Pre-run hooks:
  [ok]     capture-git-repo
  [ok]     capture-env
Post-run hooks:
  [ok]     capture-file

capsula run-dir¶

Print the run directory for a run name.

Usage¶

capsula run-dir <RUN_NAME>

Example¶

capsula run-dir happy-river

capsula push¶

Push run data to a capsula server.

Runs restored by capsula pull (marked with _capsula/pulled.json) are lossy reconstructions: a direct push of one is refused, and push --all skips them.

Usage¶

capsula push <RUN_ID_OR_NAME>
capsula push --all

Options¶

Examples¶

# Push a single run by name
capsula push happy-river

# Push a single run by ID
capsula push 01K8WSYC91YAE21R7CWHQ4KYN2

# Push all runs
capsula push --all

# Push to a specific server
capsula push happy-river --server https://capsula.example.com

capsula pull¶

Download a run from a capsula server and restore it to the local vault.

The run is restored at {YYYY-MM-DD}/{HHMMSS}-{name}, using the same layout as a locally created run. Downloaded files are verified against their recorded sizes and SHA-256 hashes. Absolute paths and paths containing .. are rejected.

Where the run lands depends on its vault:

• Runs of the configured vault go into the configured vault directory ([vault] path in capsula.toml).
• Runs of another vault go into that vault's default location, .capsula/<VAULT>/ under the project root, because the configured path describes the configured vault only.
• A --vault-path <PATH> override (or CAPSULA_VAULT_PATH) always wins and is used as the destination for either vault.

The _capsula metadata is reconstructed from the server's structured data. A _capsula/pulled.json marker records the source server and pull time.

--force only replaces runs previously created by capsula pull, as identified by _capsula/pulled.json. Locally produced runs are never overwritten. Pulled runs cannot be uploaded again with capsula push.

Usage¶

capsula pull <RUN_ID>

Options¶

Examples¶

# Pull a run by ID
capsula pull 01K8WSYC91YAE21R7CWHQ4KYN2

# Pull a run that belongs to another vault (restored into .capsula/other-vault/)
capsula pull 01K8WSYC91YAE21R7CWHQ4KYN2 --vault other-vault

# Pull a run into an explicit directory
capsula --vault-path /custom/vault/path pull 01K8WSYC91YAE21R7CWHQ4KYN2 --vault other-vault

# Pull from a specific server, replacing a previously pulled copy
capsula pull 01K8WSYC91YAE21R7CWHQ4KYN2 --server https://capsula.example.com --force

Limitations¶

A pulled run is a subset of the original local run. Data that was not uploaded by capsula push cannot be restored, including:

• symlinks
• empty directories
• files added after the push
• the original _capsula/*.json file contents
• sub-millisecond command duration

The reconstructed metadata may therefore differ from the original files. Phases with no hook outputs do not produce pre-run.json or post-run.json. Command strings stored by older server versions are normalized to JSON arrays.

capsula tui¶

Launch an interactive terminal UI for starting and ending runs.

The TUI provides a visual interface for managing manual runs, as an alternative to using run-start and run-end from the command line.

Usage¶

capsula tui

capsula vaults¶

Manage vaults on the server.

capsula vaults list¶

List all vaults on the server.

capsula vaults list
capsula vaults list --server https://capsula.example.com

Options¶