Commands
Full reference for every Semantica CLI command.
Global flags
| Flag | Description |
|---|---|
--repo <path> | Path to the Git repository (default: current directory) |
--version | Print version and exit |
--help | Show help |
enable
Initializes Semantica in the current repo. Creates .semantica/, installs Git hooks, auto-detects AI providers, and creates a baseline checkpoint.
semantica enable # First-time setup
semantica enable --force # Re-detect providers and reinstall hooks
semantica enable --providers claude-code # Non-interactive: specify providers
semantica enable --providers kiro-ide,cursor # Multiple providers
| Flag | Default | Description |
|---|---|---|
--force | false | Reinitialize even if already enabled |
--providers | auto | Comma-separated list of providers to install hooks for |
--json | false | Output as JSON |
disable
Disables Semantica. Hooks remain installed but are inert (they check for .semantica/enabled before running). Your data in .semantica/ is preserved.
semantica disable
status
Shows an overview of AI activity in the repository: enabled state, authentication, connection state, auto-playbook and MCP status, last checkpoint, recent sessions, AI attribution trend, playbook count, and detected providers.
semantica status
semantica status --json
blame
Shows AI attribution for a commit or checkpoint. Reports the percentage of changed lines that were AI-generated, broken down by file.
semantica blame HEAD # Latest commit
semantica blame abc1234 # By commit hash
semantica blame HEAD --json # Full JSON with per-file detail
If no ref is given and stdin is a terminal, an interactive checkpoint picker is shown.
| Flag | Default | Description |
|---|---|---|
--json | false | Output as JSON (includes per-file breakdown) |
explain
Explains what happened in a commit: files changed, AI involvement, session breakdown, token usage, and top edited files. Optionally generates an LLM playbook summary.
semantica explain HEAD # Commit stats + AI involvement
semantica explain abc1234 --generate # Also generate a playbook summary
semantica explain abc1234 --generate --force # Regenerate even if summary exists
semantica explain abc1234 --json # JSON output
--generate spawns a background LLM call. Run explain again after a few seconds to see the result.
| Flag | Default | Description |
|---|---|---|
--generate | false | Generate a narrative explanation using an LLM |
--force | false | Force regeneration (use with --generate) |
--json | false | Output as JSON |
suggest commit
Generates a one-line commit message from all uncommitted changes (staged, unstaged, and untracked). Analyzes the diff and recent AI session context using the first available LLM CLI. Copies the result to the clipboard automatically.
semantica suggest commit
semantica suggest commit --json
Requires at least one LLM CLI installed and authenticated: claude, cursor, gemini, or copilot.
suggest pr
Generates a PR title and body from the current branch diff against a base branch. If a pull request template exists in the repo, Semantica fills its sections rather than inventing structure.
semantica suggest pr
semantica suggest pr --base origin/main
semantica suggest pr --json
semantica suggest pr --copy
| Flag | Default | Description |
|---|---|---|
--base | auto-detect | Base branch or ref to diff against |
--json | false | Output as JSON |
--copy | false | Copy title and body to clipboard |
search
Searches playbook summaries using full-text search. Useful for finding past solutions relevant to what you're working on now.
semantica search "auth token refresh"
semantica search "error handling" --limit 5
semantica search "database migration" --json
Results include commit hash, subject, checkpoint ID, AI percentage, model, and the full playbook.
| Flag | Default | Description |
|---|---|---|
--limit | 10 | Maximum number of results |
--json | false | Output as JSON |
sessions
Lists agent sessions tracked in the repo, or views details of a specific session.
semantica sessions # Recent sessions
semantica sessions --limit 100 # More sessions
semantica sessions --all # Include sessions with no events
semantica sessions <session_id> # Session details
semantica sessions <session_id> --transcript # Full transcript
semantica sessions --json # JSON output
| Flag | Default | Description |
|---|---|---|
--limit | 20 | Maximum number of sessions to list |
--all | false | Include sessions with no events |
--transcript | false | Show the session transcript (with a session ID) |
--json | false | Output as JSON |
transcripts
Shows the agent transcript for a checkpoint, commit, or session, the sequence of user messages, assistant responses, and tool calls.
semantica transcripts HEAD # Latest commit's checkpoint
semantica transcripts abc123 # By checkpoint or commit ref
semantica transcripts abc123 --commit # Only sessions that touched files in the commit
semantica transcripts abc123 --by-session # Group events by session
semantica transcripts abc123 --cumulative # All events up to this checkpoint
semantica transcripts abc123 --raw # Include full payload JSON
semantica transcripts abc123 --verbose # Show provider, tokens, etc.
| Flag | Default | Description |
|---|---|---|
--commit | false | Only sessions touching files in the commit diff |
--by-session | false | Group events by session |
--cumulative | false | All events up to checkpoint (default: delta since previous) |
--raw | false | Include raw payload JSON from blob store |
--verbose | false | Show provider, tokens, and other fields |
--checkpoint | false | Force ref resolution as checkpoint ID |
--session | false | Force ref resolution as session ID |
--json | false | Output as JSON |
--jsonl | false | JSONL: metadata line + one event per line |
list
Lists checkpoints, most recent first.
semantica list # Last 20
semantica list -n 50 # Last 50
semantica list --json # JSON output
semantica list --jsonl # JSONL output (one object per line)
| Flag | Default | Description |
|---|---|---|
-n, --limit | 20 | Maximum number of checkpoints |
--json | false | Output as JSON |
--jsonl | false | JSONL output |
show
Shows details of a specific checkpoint: metadata, manifest hash, size, linked commit, and the full file list with blob hashes.
Checkpoint IDs are prefix-matchable.
semantica show abc123
semantica show abc123 --json
semantica show abc123 --jsonl # metadata + one file per line
checkpoint
Manually creates a checkpoint outside the normal commit flow.
semantica checkpoint -m "before big refactor"
semantica checkpoint --json
| Flag | Default | Description |
|---|---|---|
-m, --message | Checkpoint message | |
--json | false | Output as JSON |
rewind
Restores the working tree to the state captured in a checkpoint. Always creates a safety checkpoint first so you can undo the rewind.
semantica rewind abc123 # Restore files to checkpoint state
semantica rewind abc123 --exact # Also delete files not in the checkpoint
semantica rewind abc123 --no-safety # Skip safety checkpoint (dangerous)
semantica rewind abc123 --json # JSON output
| Flag | Default | Description |
|---|---|---|
--exact | false | Delete files not present in the checkpoint |
--no-safety | false | Skip creating a safety checkpoint before rewind |
--json | false | Output as JSON |
playbook use
Records that an agent applied a past playbook. Builds a reusable record of which solutions are actually being reused across sessions.
semantica playbook use abc1234 --agent claude-code --note "applied the retry pattern"
semantica playbook use abc1234 --json
| Flag | Default | Description |
|---|---|---|
--agent | Agent name (e.g. claude-code) | |
--note | How the playbook was applied | |
--json | false | Output as JSON |
agents
Manage AI agent hooks. Shows which agents are detected and which have hooks installed. In interactive mode (terminal), shows a multi-select picker. In non-interactive mode, prints a status table.
semantica agents # Interactive: toggle agent hooks
semantica agents --json # Detection and installation status as JSON
set
View or update Semantica settings for the current repo.
semantica set # Show current settings
semantica set auto-playbook enabled # Enable auto-playbook generation
semantica set auto-playbook disabled # Disable auto-playbook generation
semantica set trailers enabled # Enable attribution + diagnostics trailers
semantica set trailers disabled # Checkpoint-only commits
| Subcommand | Values | Description |
|---|---|---|
auto-playbook | enabled / disabled | LLM playbook after each commit |
trailers | enabled / disabled | Attribution and diagnostics trailers (checkpoint trailer is always included) |
auth
Manage authentication with the Semantica backend.
semantica auth login # OAuth login via GitHub or GitLab
semantica auth logout # Revoke session and delete credentials
semantica auth status # Show current auth status
auth login opens a browser for OAuth and polls until complete. Tokens are stored in OS secure storage (macOS Keychain, Linux Secret Service) when available, with automatic refresh. On headless or CI environments, credentials fall back to ~/.config/semantica/credentials.json (0600 permissions).
Set SEMANTICA_API_KEY to skip interactive auth in CI.
connect / disconnect
Connect or disconnect the current repo from the Semantica dashboard. Attribution data from connected repos is pushed to the backend for team dashboards, GitHub PR comments, and check runs.
semantica connect # Connect this repo to the dashboard
semantica disconnect # Stop syncing from this repo
Authentication via semantica auth login is required before connecting.
mcp
Manage the MCP (Model Context Protocol) server that AI agents can call natively.
semantica mcp enable # Configure all detected agents to use Semantica MCP
semantica mcp disable # Remove Semantica MCP from agent configurations
semantica mcp status # Show which agents have MCP configured
The MCP server exposes three tools:
| Tool | Purpose |
|---|---|
semantica_search | Search past playbooks for relevant solutions |
semantica_playbook_use | Record that an agent applied a playbook |
semantica_explain | Get detailed commit explanation with AI attribution |
Supported agents: Claude Code (.mcp.json), Cursor (.cursor/mcp.json), Kiro IDE (.kiro/settings/mcp.json), Kiro CLI (.kiro/agents/semantica.json), Gemini CLI (~/.gemini/settings.json), Copilot CLI (.copilot/mcp-config.json).
tidy
Safe housekeeping for Semantica state. Prunes stale broker entries, removes abandoned capture files, marks old incomplete checkpoints as failed, and removes orphan playbook FTS rows. Dry-run by default.
semantica tidy # Preview what would change
semantica tidy --apply # Apply the changes
semantica tidy --json # JSON output
completion
Generates shell completion scripts.
source <(semantica completion zsh) # Zsh
source <(semantica completion bash) # Bash
semantica completion fish | source # Fish
semantica completion powershell # PowerShell