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.

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 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¶