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

`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 — rich rows (branch · files · age), 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

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 GitHub issues for the current repository — formatted table to stdout by default, with optional JSON output for scripting.

Requires the gh CLI installed and authenticated.

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'

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 GitHub pull requests for the current repository. Same shape as coco issues, with PR-specific filter knobs.

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.

`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

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.

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# Display help
14--help
15
16# Display version
17--version

`--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 changelog

Range Selection Options

Content Options

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

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 changelog`

`coco recap`

`coco review`

`coco ui`

`coco log`

`coco issues`

`coco prs`

`coco init`

`coco doctor`

`--repo` examples