CLI Reference

Getting started

GitWhy has two interaction modes:

CLI — non-interactive output for scripting and piping
TUI — auto-opens an interactive terminal UI when stdout is a TTY

Command overview

Command	Description
`git why setup`	Set up GitWhy and configure agents
`git why save`	Save structured context locally
`git why get`	Retrieve context by ID
`git why log`	List all saved contexts
`git why tree`	Show context tree structure
`git why search`	Search contexts by keyword
`git why push`	Sync specific contexts to cloud
`git why post-pr`	Post context as PR comment

`git why setup`

Set up GitWhy globally and configure coding-agent integrations.

git why setup [flags]

Repository-local setup is deferred to the first git why save in each repository. That first save installs the post-commit hook, prepares .git/gitwhy/ local storage, saves repo-scoped credentials, and configures notes.rewriteRef. If you run git why setup inside a Git repository, GitWhy also registers that repository in your workspace. Flags:

Flag	Description	Default
`--no-ui`	Disable the rich terminal UI	`false`
`--auth-mode`	Force auth mode: `browser` or `manual`	auto
`--agents <ids>`	Comma-separated agent IDs for scripted setup	interactive
`--yes`	Accept defaults during setup	`false`
`-h`, `--help`	Show help

Examples:

# Interactive setup
git why setup

# Scripted setup without UI
git why setup --no-ui --yes

# Force browser auth
git why setup --auth-mode browser

# Select agents explicitly
git why setup --agents claude-code,codex

`git why save`

Save structured context from stdin or a file.

git why save [flags]
git why save < context.md
git why save --template          # print blank XML template
git why save --template=md       # print blank markdown template

Reads structured input from stdin or --file, injects metadata (context ID, commits), auto-categorizes, and stores the result under .git/gitwhy/contexts/. Accepts either XML format (preferred — wrap content in <context> tags) or Markdown format (legacy — use ## Section headings). Flags:

Flag	Description	Default
`--template[=xml]`	Print a blank template and exit. Values: `xml`, `md`	`xml`
`--domain <name>`	Override the domain category	auto
`--topic <name>`	Override the topic category	auto
`--file <path>`	Read context from a file instead of stdin	stdin
`--commits <sha1,sha2>`	Attach specific commit SHAs	auto-detect
`-h`, `--help`	Show help with full format guidance

Required fields (XML format): <title>, <story>, <reasoning> Required fields (Markdown format): ## Prompt, ## What Was Done, ## Reasoning Context ID, repository, branch, date, and commits are auto-populated in both formats. Examples:

# Print a blank template and fill it in
git why save --template > context.xml
# edit context.xml...
git why save --file context.xml

# Save from stdin
git why save < context.md

# Save from a file
git why save --file ./session-notes.md

# Save with explicit commits
git why save --commits a1b2c3d,d4e5f6a < context.md

# Pipe XML directly (useful for agents)
echo '<context>
  <title>Fix auth bug</title>
  <story>Fixed the null pointer in login handler.</story>
  <reasoning>User object can be nil when session expires.</reasoning>
</context>' | git why save

Run git why save --help for full format guidance including all available XML tags and markdown sections.

`git why get`

Retrieve a saved context by ID.

git why get <context-id>

Retrieves a saved context from the local repository store and prints the full markdown to stdout. Arguments:

Argument	Description
`<context-id>`	Required. The context ID to retrieve (e.g., `ctx_a1b2c3d4`)

Examples:

git why get ctx_a1b2c3d4
git why get ctx_a1b2c3d4 | less

If the context does not exist:

Context ctx_a1b2c3d4 not found.
Use 'git why log' to list saved contexts.

`git why log`

List all saved contexts.

git why log

In a TTY, opens the GitWhy TUI in the log view. In non-interactive output, prints a grouped plain-text list. Output:

my-repo (2 contexts)
  main (2)
    ├── ctx_a1b2c3d4  "JWT implementation setup"  authentication/jwt-implementation
    └── ctx_e5f6g7h8  "OAuth flow configuration"  authentication/oauth-flow

If no contexts exist:

No contexts saved yet.
Tell your coding agent: "save this session with GitWhy"

`git why tree`

Display the domain and topic context tree.

git why tree

Like git why log, opens the TUI when stdout is a terminal. In non-interactive output, prints the tree in plain text. Output:

main
  authentication/
    jwt-implementation/
      ctx_a1b2c3d4  "JWT implementation setup"
  api-design/
    rate-limiting/
      ctx_i9j0k1l2  "Rate limiting middleware"

`git why search`

Search saved contexts using hybrid full-text search across local and cloud workspace contexts.

git why search "query" [flags]

When a query is provided, prints ranked plain text results with scores, snippets, and file paths. Without a query, opens the interactive TUI with filter-as-you-type. Arguments:

Argument	Description
`"query"`	Search query — natural language or specific terms (file paths, function names, commit SHAs). Omit to open interactive TUI

Flags:

Flag	Description	Default
`--repo`	Filter to a specific repository (owner/name)	current repo
`--domain`	Filter to a specific domain (e.g., ‘architecture’)	all
`--limit`	Max results to return	10 (max 20)
`--local-only`	Search local contexts only (skip cloud)	false
`--no-tui`	Print plain text results even without a query	false

Output:

  ctx_a1b2c3d4  0.87  JWT implementation setup  [authentication/jwt-implementation]
    We chose JWT because the mobile app needs stateless auth...
    files: api/auth/jwt.go, api/auth/middleware.go
1 result(s) found

Examples:

git why search jwt
git why search "src/auth/middleware.ts"
git why search --domain architecture "billing"
git why search --local-only "migration"

`git why push`

Sync specific contexts to GitWhy cloud. Requires one or more context IDs.

git why push <context-id> [context-id...] [flags]

By default, contexts are synced as private. Pass --share to publish them as team-visible. Flags:

Flag	Description	Default
`--share`	Publish synced contexts as shared/team-visible	`false`
`--force`	Skip all dedup checks and re-sync even if already synced	`false`
`-h`, `--help`	Show help

Output:

# Private sync
Synced 1 context(s) to cloud (private). Use --share to publish.

# With --share
Push complete: 1 published

# No matching contexts
no matching local contexts found for: ctx_abc123
Run 'git why log' to see available contexts

Examples:

# Sync a single context as private
git why push ctx_a1b2c3d4

# Sync multiple contexts
git why push ctx_a1b2c3d4 ctx_e5f6g7h8

# Sync and publish to team
git why push ctx_a1b2c3d4 --share

# Force re-sync a stuck context (bypasses all dedup checks)
git why push ctx_a1b2c3d4 --force

Requires credentials. If none are available, the CLI exits with: missing API key. Run 'git why setup' first. Run git why log to see available context IDs.

Cloud verification (v0.6.7+): Before skipping a context, the CLI verifies it actually exists on the cloud — not just in the local push-state cache. This auto-heals most sync issues. Use --force only when even the cloud check doesn’t resolve the problem.

`git why post-pr`

Post context summary as a PR comment. Contexts are matched to the PR by verifying commit SHAs or branch name.

git why post-pr [context-id...] [flags]

Without context IDs, auto-matches all local contexts against the PR’s commits. With IDs, filters to those and validates they belong to the PR. Flags:

Flag	Description	Default
`--pr`	Target a specific PR number (auto-detected from branch if omitted)	`0` (auto)
`--branch`	Branch name to find PR for (e.g., `docs-fix`). Useful when running from a different branch or worktree	none (auto)
`--dry-run`	Show what would be posted without posting	`false`
`--force`	Skip confirmation prompt	`false`
`-h`, `--help`	Show help

PR auto-detection: When no --pr or --branch is specified, GitWhy first checks the current branch for an open PR. If none is found, it scans all open PRs and matches them against branches in your saved contexts. This means you can run git why post-pr from main and it will find PRs for contexts saved on feature branches. Output:

Finding PR...
  ✓ PR #42: https://github.com/.../pull/42 (feat/auth)

Matching contexts to PR...
  ✓ ctx_a1b2 — "Add JWT middleware" (commit matched)
  ✗ ctx_e5f6 — "Fix billing bug" — skipped: commits not in PR #42

Post 1 context(s) to PR #42? [Y/n] y

Syncing contexts to cloud... done
Posting comment as gitwhy-bot... done

✓ Comment posted: https://github.com/.../pull/42

Examples:

# Auto-match all contexts to current branch's PR
git why post-pr

# Post to a PR on a different branch (e.g., from main or a worktree)
git why post-pr --branch feat/auth

# Post specific contexts
git why post-pr ctx_a1b2c3d4 ctx_e5f6g7h8

# Target a specific PR by number
git why post-pr --pr 42

# Preview without posting
git why post-pr --dry-run

Requires the GitHub App installed on the repository, a GitWhy API key, and the GitHub CLI (gh) authenticated. Contexts are auto-synced and published before posting.

Help behavior

GitWhy uses Cobra help flags across all commands:

git why <command> -h — shows the command help
git why <command> --help — shows the command help
git why <command> -help — invalid (parsed as short flags)

Getting Started

Core Features

Sharing & Collaboration

Interfaces

Integration Guide

Context Format

Plans & Pricing

CLI Reference

Getting started

Command overview

`git why setup`

`git why save`

`git why get`

`git why log`

`git why tree`

`git why search`

`git why push`

`git why post-pr`

Help behavior

See also

​Getting started

​Command overview

​git why setup

​git why save

​git why get

​git why log

​git why tree

​git why search

​git why push

​git why post-pr

​Help behavior

​See also

Getting started

Command overview

`git why setup`

`git why save`

`git why get`

`git why log`

`git why tree`

`git why search`

`git why push`

`git why post-pr`

Help behavior

See also