CLI Reference

The primary way to use claustre is the TUI dashboard — just run claustre. The CLI commands below are an alternative for scripting or when you prefer the terminal.

Dashboard

claustre                  # Launch TUI (default command)
claustre dashboard        # Same as above, explicit

The default command opens the terminal dashboard where you can manage projects, create and launch tasks, monitor sessions, and interact with embedded Claude Code terminals.

Project Management

claustre add-project <name> [path]         # Register a project (path defaults to ".")
claustre remove-project <name>             # Remove a project and its data
claustre list-projects                     # List all projects with session/task counts

add-project — Registers a git repository as a claustre project. The path defaults to the current directory if omitted.

remove-project — Removes a project and all its associated tasks and sessions from the database.

list-projects — Shows all registered projects with their task and session counts.

Task Management

claustre add-task <project> <title> [-d description] [-m mode]
claustre list-tasks <project>
claustre export <project> [-o path]

add-task — Creates a new task for a project. Mode can be supervised (default, one task at a time with user interaction), autonomous (auto-chains the next task from the queue when done), or exploration (open-ended research). The CLI only supports setting mode and description; other parameters (base, branch, push mode, review loop, subtasks) require the TUI task form.

list-tasks — Lists all tasks for a project with status symbols: ⧖ pending, ● working, ◐ in_review, ✓ done, ✗ error.

export — Exports all tasks and project stats to a JSON file. Defaults to <project>-export.json in the current directory.

Statistics

claustre stats <project>

Shows aggregate statistics for a project: total tasks completed, total sessions, time spent, tokens used, and cost.

Skills (skills.sh)

claustre skills                            # List installed global skills
claustre skills find <query>               # Search the skills.sh registry
claustre skills add <package> [-p project] # Install a skill (globally or per-project)
claustre skills remove <name> [-p project] # Remove a skill
claustre skills update                     # Update all installed skills

Skills are managed via skills.sh, a package registry for Claude Code skills. They extend Claude's capabilities with domain-specific knowledge and tools.

skills (no subcommand) — Lists all globally installed skills.

skills find — Searches the skills.sh registry for packages matching the query.

skills add — Installs a skill package. By default, skills are installed globally. Use -p project to install per-project.

skills remove — Removes an installed skill. Use -p project to remove a per-project skill.

skills update — Updates all installed skills to their latest versions.

The TUI also has a skills panel (press i) for browsing and managing skills interactively.

Desktop App

claustre app                           # Launch the native macOS desktop app

Opens the native macOS desktop application built with Tauri. The desktop app provides the same project and task management features as the TUI in a windowed GUI. See the Desktop App page for details.

Setup & Maintenance

claustre configure                     # Onboarding wizard: check prerequisites, configure permissions
claustre health-check                  # Verify the binary is functional (used by auto-update)
claustre rollback                      # Revert to previous binary after a bad update

configure — An interactive onboarding wizard that:

• Checks that prerequisites are installed (git, claude, gh)
• Compares your ~/.claude/settings.json permissions against the recommended set (defined in [permissions] in config.toml) and offers to apply missing entries

The TUI also runs a sanity check on startup — a warning banner appears in the title bar if permissions are misaligned, and pressing c opens the configure overlay.

health-check — Prints a success message and exits. Used internally by the auto-update process to verify that a newly downloaded binary works before replacing the current one.

rollback — Replaces the current claustre binary with the backup stored at ~/.claustre/bin/claustre.prev. Use this if an auto-update introduced a broken build.

Sync

claustre sync init [url]              # Initialize sync repo (clone if URL given)
claustre sync push                    # Export state, commit, push
claustre sync pull                    # Pull from remote, import into local DB
claustre sync cd                      # Change to sync directory (requires shell-init)
claustre shell-init                   # Print shell integration script

sync init — Sets up a git repo at ~/.claustre/sync/. If a URL is provided, clones from it. Otherwise initializes a new local repo (add a remote later with git -C ~/.claustre/sync remote add origin <url>).

sync push — Exports all projects, tasks, and subtasks as JSON files to the sync repo, commits, and pushes to the remote. Idempotent — does nothing if state hasn't changed.

sync pull — Pulls from the remote and upserts tasks into the local database. Projects are matched by name. Unregistered projects are skipped with a message.

sync cd — Changes to the sync directory (~/.claustre/sync/). Requires shell integration: add eval "$(claustre shell-init)" to your .zshrc or .bashrc. Without shell integration, prints the path to stdout.

shell-init — Prints a shell function that wraps claustre to enable commands that need to affect the parent shell (like sync cd). Add eval "$(claustre shell-init)" to your shell rc file.

See Sync Across Machines for setup guides and detailed workflows.

Internal Commands

claustre also has internal commands used by hooks and the autonomous task runner. These are not meant to be run manually.

session-update — Called by the Stop and UserPromptSubmit hooks to sync session state back to the database. Updates Claude status, detects PRs, records token usage, and handles task status transitions.

feed-next — The autonomous task chain runner. Runs as a blocking loop inside an embedded PTY: picks the next pending autonomous task, launches Claude as a subprocess, waits for completion, then loops to pick up the next task.

session-host — A detached PTY owner that runs as a separate process and serves the PTY over a Unix socket. Survives TUI restarts — the TUI reconnects to existing session-hosts on startup.

review-loop — Monitors an in_review task's PR for new comments. Polls at a configurable interval, launches Claude to evaluate and implement accepted feedback, then loops. Spawned automatically by the TUI when a task with the review loop flag transitions to in_review.