Command Reference

Complete reference for all coco commands with detailed options and examples.

Smart default routing

As of 0.57.0, running coco with no subcommand is a smart entry point — it probes your environment and routes you to the right surface instead of always running a commit:

Situation	Where you land
No coco config yet (fresh install)	`coco init` — the setup wizard
Configured and inside a git repo	`coco ui` — the full workstation
Configured but not in a git repo	`coco workspace` — the multi-repo view

This matches lazygit / tig / gitui (bare invocation opens the UI) and stops fresh installs from landing in an API-key error. --repo / --cwd are honored before routing.

To generate a commit, call the subcommand explicitly: coco commit. Scripts and aliases using coco commit are unaffected. To restore the legacy "bare coco = commit" behavior, pass --commit or set COCO_DEFAULT=commit.

`coco commit`

Generates commit messages based on staged changes with intelligent commitlint integration.

bash

coco commit

0.57.0+: bare coco (no subcommand) is now a smart entry point — it no longer defaults to commit. Use coco commit (as shown throughout this section), or pass --commit / set COCO_DEFAULT=commit to restore the legacy default.

Basic Options

bash

1# Interactive mode - opens editor for review and editing
2coco commit -i, --interactive
3
4# Verbose output - shows detailed processing information
5coco commit --verbose
6
7# Help - display command help
8coco --help

Commit Enhancement Options

bash

1# Add content to the end of the generated commit message
2coco commit --append "Resolves #128"
3
4# Automatically append Jira/Linear ticket ID from branch name
5coco commit -t, --append-ticket
6
7# Add extra context to guide commit generation
8coco commit -a, --additional "Resolves UX bug with sign up button"
9
10# Include previous commits for context (specify number)
11coco commit -p, --with-previous-commits 3

Conventional Commits Options

bash

1# Force conventional commits mode
2coco commit -c, --conventional
3
4# Include/exclude branch name in context (default: true)
5coco commit --include-branch-name
6coco commit --no-include-branch-name

Processing Options

bash

1# Ignore specific files (can be used multiple times)
2coco commit --ignored-files "*.lock" --ignored-files "dist/*"
3
4# Ignore file extensions (can be used multiple times)  
5coco commit --ignored-extensions ".map" --ignored-extensions ".min.js"
6
7# Use basic git status instead of full diff (faster for large changes)
8coco commit --no-diff
9
10# Open commit message in editor before proceeding
11coco commit --open-in-editor
12
13# Skip pre-commit and commit-msg hooks (passes --no-verify to git commit)
14coco commit -n, --no-verify

Examples

bash

1# Basic conventional commit
2coco commit --conventional
3# Output: feat: add user authentication system
4
5# With scope and context
6coco commit --conventional -a "fixes login timeout"
7# Output: fix(auth): resolve login timeout issue
8
9# With additional context and ticket
10coco commit --conventional --additional "Resolves login issues" --append-ticket
11# Output: feat(auth): add OAuth2 integration
12#         
13#         Implement OAuth2 flow with Google and GitHub providers.
14#         Resolves login issues
15#         
16#         Part of **PROJ-123**

`coco commit split`

Split staged changes into multiple coherent commits. This is useful when you have a broad set of staged changes that logically belong in separate commits.

bash

1# Generate a split plan (non-mutating — reads staged changes and proposes groups)
2coco commit split --plan
3
4# Apply a generated plan (creates one commit per group)
5coco commit split --apply
6
7# Shorthand: --split is equivalent to --plan
8coco commit --split

How It Works

--plan reads your staged changes, condenses the diffs, builds a hunk inventory for modified files, and asks the configured model to group files (or individual hunks) into proposed commits. It prints the plan but does not change git state.

--apply starts from a generated plan and creates one commit per group:

Whole-file groups stage the listed files. If a planned file also has unstaged or untracked changes, apply aborts for that group to avoid mixing unrelated work.
Hunk groups apply selected staged hunks directly to the index with git apply --cached, allowing separate commits from different parts of the same file.

Safety Rules

Every staged file must appear exactly once in the plan.
A file is assigned either as a whole file or by all of its hunk IDs, never both.
If a file is split by hunks, every generated hunk must be assigned exactly once.
Hunk-level apply is fail-closed: if a patch cannot be applied cleanly after earlier split commits have changed the file, the command stops and leaves remaining changes for manual review.

Configuration

coco commit split requires a configured AI provider. Pass -i (or set "mode": "interactive" in your config) so the plan is displayed for review:

bash

coco commit split --plan -i

Examples

bash

1# Stage everything and generate a split plan
2git add .
3coco commit split --plan -i
4
5# Review the plan, then apply it
6coco commit split --apply -i

`coco amend`

Regenerate the last commit's message from its diff and rewrite it via git commit --amend.

bash

# Regenerate the last commit message and amend in place
coco amend

Any currently-staged changes are folded into the amend (just as git commit --amend does), and the regenerated message reflects the combined diff. When staged changes are present, coco prints a note that they will be included before amending. If there is no commit to amend, the command exits non-zero.

Options

bash

1# Review the regenerated message, then apply / edit in $EDITOR / cancel
2coco amend -i, --interactive
3
4# Print the regenerated message without amending
5coco amend --dry-run
6
7# Emit { previous, message } as JSON without amending
8coco amend --json
9
10# Force conventional commits mode
11coco amend -c, --conventional
12
13# Add extra context to guide regeneration
14coco amend -a, --additional "Clarify the rate-limit fix"
15
16# Skip pre-commit and commit-msg hooks (passes --no-verify to git commit)
17coco amend -n, --noVerify

Examples

bash

1# Tweak the message of the commit you just made
2coco amend -i
3
4# Stage a forgotten file, then fold it into the last commit with a fresh message
5git add src/forgotten.ts
6coco amend
7
8# Preview what the new message would be without touching history
9coco amend --dry-run

`coco changelog`

Creates changelogs from commit history.

bash

1# Basic changelog for current branch
2coco changelog
3
4# Interactive mode
5coco changelog -i, --interactive

Range Selection Options

bash

1# Specific commit range (HEAD references)
2coco changelog -r HEAD~5:HEAD
3
4# Specific commit range (commit hashes)  
5coco changelog -r abc1234:def5678
6
7# Compare against target branch
8coco changelog -b main, --branch main
9
10# Compare against a tag
11coco changelog -t 3.0.0, --tag 3.0.0
12
13# All commits since last tag
14coco changelog --since-last-tag

--branch, --tag, and --since-last-tag cannot be combined in the same run.

Content Options

bash

1# Include diff for each commit in analysis
2coco changelog --with-diff
3
4# Generate changelog based only on branch diff
5coco changelog --only-diff
6
7# Include author attribution
8coco changelog --author
9
10# Add extra context to guide generation
11coco changelog -a "Focus on user-facing changes"

`coco pr create`

Generate a PR title and body from the current branch's diff against the base branch (reusing the changelog generator) and open it with the matching forge CLI.

bash

# Generate a PR for the current branch and open it
coco pr create

coco auto-detects the forge (GitHub, GitHub Enterprise, or GitLab) from the git remote host, auto-detects the base branch, and checks whether the matching CLI is available — gh for GitHub / GitHub Enterprise, glab for GitLab. On GitLab this creates a merge request and pushes the source branch automatically. It refuses to run from the base branch, and exits 0 (a no-op) if a PR / MR already exists for the branch.

Options

bash

1# Target a specific base branch (default: repo default branch)
2coco pr create -b main, --base main
3
4# Open as a draft PR
5coco pr create -d, --draft
6
7# Override the generated title / body
8coco pr create --title "Add OAuth2 login" --body "Implements the PKCE flow."
9
10# Open the PR in the browser after creating it
11coco pr create -w, --web
12
13# Review / edit the generated title and body before creating
14coco pr create -i, --interactive
15
16# Print the generated PR without creating it
17coco pr create --dry-run
18
19# Emit the generated PR as JSON without creating it
20coco pr create --json

Examples

bash

1# Generate and open a PR against main
2coco pr create -b main -w
3
4# Review the generated content before it's submitted
5coco pr create -i
6
7# Preview the title + body without calling gh
8coco pr create --dry-run

`coco recap`

Summarize changes across different time periods.

bash

1# Summarize current working directory changes
2coco recap
3
4# Interactive mode
5coco recap -i, --interactive

Time Period Options

bash

1# Yesterday's changes
2coco recap --yesterday
3
4# Last week's changes  
5coco recap --last-week, --week
6
7# Last month's changes
8coco recap --last-month, --month
9
10# Changes since last git tag
11coco recap --last-tag, --tag
12
13# Current branch changes
14coco recap --current-branch

`coco review`

Perform AI-powered code review on your changes.

bash

1# Review current working directory changes
2coco review
3
4# Interactive mode
5coco review -i, --interactive
6
7# Review specific branch
8coco review -b feature-branch, --branch feature-branch
9
10# Scope the review to staged changes only
11coco review --staged
12
13# Exit non-zero when any finding is at or above the threshold (1-10) — for CI gating
14coco review --severity 7

--severity <n> makes coco review fail the process when any finding's severity is at or above <n>, so it can gate a CI pipeline. --staged limits the review to the staged diff. Pair with the global --json flag for machine-readable findings.

`coco ui`

Open the full-screen Git workstation TUI.

bash

1# Start in history mode
2coco ui
3
4# Start in status or diff mode
5coco ui --view status
6coco ui --view diff
7
8# Apply history filters before opening
9coco ui --all
10coco ui --branch feature/my-branch
11coco ui --path src --limit 500
12
13# Pick a theme preset
14coco ui --theme catppuccin

coco ui supports:

sixteen top-level views — history, status, diff, compose, branches, tags, stash, worktrees, pull-request, PR triage, issues, conflicts, reflog, bisect, submodules, and changelog — reachable from any other view via g-prefixed chords (g h/g s/g d/g c/g b/g t/g z, and so on),
a navigation stack with < / Esc to pop back, plus a ›-separated breadcrumb in the header,
file-level and hunk-level stage/unstage with confirmation-gated revert,
commit compose as a top-level view with editable summary/body, hook feedback, and explicit AI commit draft generation,
an interactive command palette (:) with fuzzy filter and recently-used at the top, runnable from any view,
/ global search across history, branches, tags, and stash,
a full stash workflow — an aligned table (ref · age · branch · files · message), gZ to stash from any view, and stash-view actions (R rename, b branch, A apply --index, u undo-drop),
a single-pane fallback for narrow terminals (under ~100 cols / 80×24 tmux splits): the panes fold to one full-width view you Tab between, with v to peek the sidebar.

See Coco UI for the full workstation guide and per-view actions.

`coco log`

Explore commit history with stdout, JSON, commit detail, and full-screen interactive TUI modes.

bash

1# Compact first-parent history
2coco log
3
4# Interactive terminal UI, equivalent to coco ui --view history
5coco log -i, --interactive
6
7# Full graph across all local and remote refs
8coco log --all --view full
9
10# Machine-readable output
11coco log --format json
12
13# Single commit metadata and changed files
14coco log --commit HEAD

History Selection Options

bash

1# Limit loaded commits
2coco log --limit 100
3
4# Choose compact, graph, or full view
5coco log --view compact
6coco log --view graph
7coco log --view full
8
9# Include all refs
10coco log --all
11
12# Show a specific branch/ref
13coco log --branch feature/my-branch
14
15# Include or exclude merge commits
16coco log --merges
17coco log --no-merges

Plain stdout and JSON modes default to 30 commits. Interactive mode defaults to 300 commits so coco log -i has a broader browsing window. Passing --limit overrides either default.

Filter Options

bash

1# Filter by author
2coco log --author "Grace Hopper"
3
4# Filter by date range
5coco log --since "2026-04-01" --until "2026-04-30"
6
7# Filter by changed path
8coco log --path src --path README.md
9
10# Pickaxe: commits that changed the occurrence count of a string (git log -S)
11coco log --pickaxe useState
12
13# Grep-diff: commits whose patch matches a regex (git log -G)
14coco log --grep "^export function"

--pickaxe and --grep (0.81.0) are the CLI counterparts of the interactive TUI's S:/G: filter prefixes (see Interactive TUI below).

Interactive TUI

coco log -i opens coco ui --view history with:

repository/sidebar tabs for status, branches, tags, stashes, and worktrees,
a searchable commit graph/list,
selected commit metadata,
changed files, numstat totals, and selected-file hunk previews,
command palette, help panel, and confirmation prompts for advanced workflows.

Common keys:

Key	Action
`q`, `Ctrl+C`	Quit
`/`	Search/filter the active view
`?`	Help (grouped Global / This view)
`<`, `Esc`	Pop the navigation stack (back)
`j` / `k`, arrows	Move in focused panel
`g h`/`g s`/`g d`/`g c`/`g b`/`g t`/`g z`	Jump to history/status/diff/compose/branches/tags/stash
`gg` / `G`	Jump to first/last visible commit
`n` / `N`	Next/previous visible search result
`Tab` / `Shift+Tab`	Move focus
`[` / `]`	Cycle sidebar tabs
`1`-`5`	Jump to sidebar tabs
`\`	Toggle compact/full graph (was `g` before v0.34.0)
`r`	Refresh repository context
`:`	Open the interactive command palette

See Coco UI for the full workstation guide and Interactive Log TUI for the history-specific guide.

`coco issues`

List issues for the current repository — formatted table to stdout by default, with optional JSON output for scripting.

Works across GitHub, GitHub Enterprise, and GitLab — coco auto-detects the forge from the git remote host. Requires the matching CLI installed and authenticated: gh for GitHub / GitHub Enterprise, glab for GitLab (glab auth login).

bash

1# Open issues in the current repo
2coco issues
3
4# Filter by state
5coco issues --state closed
6coco issues --state all
7
8# Filter by assignee / author
9coco issues --assignee @me      # or --mine for shorthand
10coco issues --author gfargo
11
12# Filter by labels (comma-separated for AND)
13coco issues --label bug,critical
14
15# Free-form GitHub search syntax
16coco issues --search "auth flow"
17
18# Tune the page size
19coco issues --limit 50
20
21# Machine-readable output
22coco issues --json | jq '.[] | .title'

The same flags and filters work on every forge. On GitLab, --mine / --author @me map to GitLab's scope filter.

Cache control

coco issues writes results to ~/.cache/coco/github/ (or $XDG_CACHE_HOME/coco/github/) with a 5-minute TTL. Triage tends to be bursty, so the cache pays for itself quickly.

bash

1# Force a fresh gh call (writes through to cache)
2coco issues --refresh
3
4# Skip the cache entirely (no read, no write)
5coco issues --no-cache
6
7# Clear the entire triage cache directory
8coco cache clear-github

The repo header tag reads cached Ns ago on cache hits so you can always tell when a list is fresh vs warm.

`coco prs`

List pull requests for the current repository. Same shape as coco issues, with PR-specific filter knobs. Works across GitHub, GitHub Enterprise, and GitLab — on GitLab this lists merge requests. Requires gh (GitHub / GitHub Enterprise) or glab (GitLab) installed and authenticated.

bash

1# Open PRs (default)
2coco prs
3
4# State (PRs have a merged variant distinct from closed)
5coco prs --state merged
6coco prs --state all
7
8# Targeting
9coco prs --draft
10coco prs --mine                 # = --author @me
11coco prs --base main            # PRs targeting `main`
12coco prs --head feature/auth    # PRs from `feature/auth`
13
14# Cache flags work identically to `coco issues`
15coco prs --refresh
16coco prs --no-cache

Both commands are companion CLI entrypoints to the g i and g P triage chords inside coco ui. See Issue & PR Triage for the full action key reference, filter preset cycling, and inspector hydration details, and Multi-Forge Support for forge detection and the gh / glab requirements.

`coco init`

Interactive setup wizard for configuring coco.

bash

1# Setup wizard (will prompt for scope)
2coco init
3
4# Configure for current project only
5coco init --scope project
6
7# Configure globally for current user
8coco init --scope global

`coco doctor`

Check your configuration for common issues and suggest fixes.

bash

1# Run diagnostics
2coco doctor
3
4# Auto-fix what can be fixed
5coco doctor --fix
6
7# Show the per-task model routing profile (and usage, when enabled)
8coco doctor --cost
9
10# Delete the local usage-stats ledger
11coco doctor --clear

coco doctor inspects your merged configuration (project file, git config, env vars, defaults) and reports:

Errors: missing provider, missing API key, invalid JSON in config file
Warnings: outdated model names with newer replacements, Ollama misconfiguration, low token limits, placeholder API keys
Info: mode set to stdout (interactive features need -i), dynamic routing status, missing $schema field

With --fix, it writes auto-fixable changes (model upgrades, Ollama auth cleanup, token limit bumps, $schema addition) directly to .coco.config.json.

This is useful when upgrading coco versions — run coco doctor after updating to see if your config needs attention.

`coco doctor --cost`

--cost prints the per-task model routing profile — which model each of the eight dynamic-model tasks (summarize, commit, commitSplit, changelog, review, recap, repair, largeDiff) resolves to under the active preference.

When usage recording is enabled, it also prints aggregated token and latency usage by task, model, and repo from a cross-run ledger. As of 0.69 recording is opt-out and local-only: the first interactive run defaults it on after a one-time notice, coco init asks, and the data never leaves your machine (it records no prompt, diff, or code content). Opt out anytime with coco init, telemetry.usage: false, or COCO_USAGE_LOG=0. See Local usage stats for the full story. Add --json for machine-readable output (it includes a byRepo array).

coco doctor --clear deletes the local usage ledger.

bash

1# Just the routing profile (works with no usage history)
2coco doctor --cost
3
4# Routing profile plus aggregated usage by task, model, and repo
5coco doctor --cost
6
7# Machine-readable (includes byRepo)
8coco doctor --cost --json
9
10# Delete the local usage-stats ledger
11coco doctor --clear

Global Options

These options work with all commands — they're inherited at the yargs root, so any subcommand sees them:

bash

1# Target a specific repository directory (alias: --cwd)
2# Lets you drive coco against any repo without `cd`-ing first.
3# Every command — commit, log, ui, recap, changelog, review,
4# cache, doctor, init — respects this.
5--repo <dir>
6
7# Verbose output for debugging
8--verbose
9
10# Interactive mode (where supported)
11-i, --interactive
12
13# Machine-readable output where supported (changelog, recap, review,
14# plus the --json flags on amend, pr create, doctor --cost)
15--json
16
17# Suppress status chrome (spinners, banners) but keep the result
18-q, --quiet
19
20# Display help
21--help
22
23# Display version
24--version

--json emits structured output on the commands that support it (changelog, recap, review, plus the dedicated --json flags on coco amend, coco pr create, and coco doctor --cost). -q / --quiet strips status chrome so only the result reaches stdout — handy when piping into other tools.

`--repo` examples

bash

1# Generate a commit message for another project from your current shell
2coco commit --repo ~/work/api
3
4# Open the workstation against any repo without cd
5coco ui --repo ~/work/api
6
7# Inspect another repo's log
8coco log --repo ~/work/api --limit 10
9
10# Run the doctor against a specific project
11coco doctor --repo ~/work/api
12
13# Initialize a project config without cd
14coco init --repo ~/work/api --scope project
15
16# All of the above also accept `--cwd` as an alias
17coco commit --cwd ~/work/api

When --repo is set, coco chdirs to the path up-front and binds its git instance to it, so config lookup, commitlint discovery, simple-git operations, and downstream path resolution all see the same root.

Common Workflows

Daily Development

bash

1# Make changes
2git add .
3
4# Generate and review commit
5coco commit -i

Team Workflow with Validation

bash

1# Stage changes
2git add .
3
4# Generate conventional commit with ticket
5coco commit --conventional --append-ticket -i

Release Workflow

bash

1# Generate changelog for release
2coco changelog --since-last-tag
3
4# Review recent release history interactively
5coco log -i --since "2026-04-01"
6
7# Create release commit
8git add .
9coco commit --conventional -a "Release version 1.2.0"

Code Review Workflow

bash

1# Review changes before committing
2coco review
3
4# Generate commit after review
5coco commit --conventional -i

Output Modes

Stdout Mode (Default)

bash

1# Generate message to stdout
2coco commit
3
4# Use with git commit
5git commit -m "$(coco commit)"
6
7# Pipe to git commit
8coco commit | git commit -F -

Interactive Mode

bash

1# Review and edit before committing
2coco commit -i
3
4# Set as default in config
5{
6  "mode": "interactive"
7}

Configuration Integration

All commands respect your configuration settings:

bash

1# Use project config
2coco commit  # Uses .coco.config.json settings
3
4# Override with environment variables
5COCO_MODE=interactive coco commit
6
7# Override with command line flags
8coco commit --conventional --interactive

For complete configuration options, see the Configuration Overview.

Command Reference

Smart default routing

coco commit

Basic Options

Commit Enhancement Options

Conventional Commits Options

Processing Options

Examples

coco commit split

How It Works

Safety Rules

Configuration

Examples

coco amend

Options

Examples

coco changelog

Range Selection Options

Content Options

coco pr create

Options

Examples

coco recap

Time Period Options

coco review

coco ui

coco log

History Selection Options

Filter Options

Interactive TUI

coco issues

Cache control

coco prs

coco init

coco doctor

coco doctor --cost

Global Options

--repo examples

Common Workflows

Daily Development

Team Workflow with Validation

Release Workflow

Code Review Workflow

Output Modes

Stdout Mode (Default)

Interactive Mode

Configuration Integration

`coco commit`

`coco commit split`

`coco amend`

`coco changelog`

`coco pr create`

`coco recap`

`coco review`

`coco ui`

`coco log`

`coco issues`

`coco prs`

`coco init`

`coco doctor`

`coco doctor --cost`

`--repo` examples