Use GitGhost From Your Terminal

GitGhost AI CLI is the bridge between local developer work and the GitGhost AI project record. Install it when you want to keep using Claude Code, Codex, Gemini CLI, Cursor, OpenCode, or another local coding agent, while GitGhost AI keeps the work visible for review.

Why It Matters

Without the CLI, local AI work often stays trapped in one terminal: prompts, generated files, tool calls, failed commands, and security checks are hard for the rest of the team to inspect. With the CLI connected to a project, GitGhost AI can turn that work into evidence your team can review before code ships.

Local-only workflow	GitGhost CLI workflow
Agent work is visible only on one machine.	Sessions, activity, checkpoints, and contribution evidence appear in GitGhost AI.
A reviewer sees only the final diff.	A reviewer can inspect the request, transcript evidence, files touched, action requests, and linked commits.
Scripts and agents need broad credentials or manual copy/paste.	The CLI uses account login, project-scoped connect codes, and project-scoped Git credentials.
Risky actions happen outside the platform.	Local agents can request governed actions such as security scans, patch proposals, branch work, and merge requests.
Git push often fails until credentials are configured manually.	gitghost-cli project git-credentials stores the right HTTPS credential for the project remote.

The first value to look for is simple: after setup, your local agent work should show up in GitGhost AI as an AI session, AI activity, or an approval/action request that a reviewer can inspect.

Install

curl -fsSL https://gitghost.ai/install.sh | bash

The installer prints the CLI version, detected platform, install directory, checksum verification, installed binary path, PATH status, and a first-run checklist.

Optional controls:

curl -fsSL https://gitghost.ai/install.sh | bash -s -- --dir /usr/local/bin
curl -fsSL https://gitghost.ai/install.sh | bash -s -- --version v0.1.0-prod.176

First Win In 10 Minutes

Use this flow when you want to prove the CLI is useful on a real project.

1. Sign In From The Terminal

gitghost-cli auth login
gitghost-cli auth status

gitghost-cli auth login prints a one-time device code and opens a browser approval page. Approve the browser page only when the code matches the terminal.

If you are already signed in to GitGhost AI in the browser, the approval page uses that browser account. If it is the wrong account, sign out first and reopen the device URL from the CLI.

2. Generate A Project Connect Code

Open the project in GitGhost AI, then open the AI chat or local agent panel and generate a local-agent connect code.

There are two different codes:

Code	Created By	Used For
CLI login code	gitghost-cli auth login	Signing this terminal into your GitGhost AI account.
Local-agent connect code	GitGhost AI project UI	Linking one local coding agent to one project.

Do not use the CLI login code with agent connect.

3. Connect Your Local Agent

Run the command shown in the GitGhost AI UI. The common shape is:

gitghost-cli setup --agent claude-code --code <connect-code>

You can also run the lower-level commands directly:

gitghost-cli agent connect --agent claude_code --code <connect-code>
gitghost-cli agent add claude-code
gitghost-cli status

Use the agent identifier that matches your local tool.

Agent	Example Identifier	What To Expect
Claude Code	claude_code or claude-code	GitGhost-managed hook and MCP setup when enabled.
Codex	codex	GitGhost-managed hook setup when enabled.
Gemini CLI	gemini_cli or gemini	Connect and sync support when enabled by project policy.
Cursor	cursor	Connect and sync support when enabled by project policy.
OpenCode	opencode	Connect and sync support when enabled by project policy.

gitghost-cli setup ends with a completed/remaining checklist. If something is missing, run the next command it prints instead of guessing flags.

4. Do A Small Local Agent Task

Run your local agent from the project checkout and start with a small, reviewable task:

Inspect the repository and summarize the main test command.
Do not create commits, branches, merge requests, or issues.

Then open GitGhost AI and check:

• AI Activity for account-level agent activity.
• Agent Sessions for the session record.
• Session Detail for transcript evidence, checkpoints, files touched, and action requests.

This is the moment the CLI should make sense: the local terminal session becomes something the team can inspect in the platform.

High-Value Workflows To Try Next

Make Local AI Work Reviewable

Use the CLI when you want local agent work to become a reviewable project record:

gitghost-cli status
gitghost-cli agent list
gitghost-cli agent-help

gitghost-cli status shows account, project, repository, hook, and credential readiness without printing tokens. gitghost-cli agent-help gives local coding agents a safe command map so they do not guess GitGhost flags or ask users for tokens.

Request A Governed Security Scan

Connected local agents can ask GitGhost AI to run platform actions under project policy:

gitghost-cli agent request-action \
  --session-id <agent-session-id> \
  --tool run_security_scan \
  --input '{"scan_type":"full"}'

If approval is required, GitGhost AI creates an approval request instead of letting the local agent run the action silently.

Submit Local Changes As A Patch Proposal

When a local agent changes files, you can submit those changes as a governed patch proposal instead of giving the agent broad push credentials:

gitghost-cli agent propose-patch \
  --session-id <agent-session-id> \
  --repo /path/to/project \
  --base-commit <sha-before-agent-work> \
  --summary "Describe the local agent work"

Reviewers can inspect the request and decide what should be applied inside GitGhost AI.

Store HTTPS Git Credentials

CLI login signs in the terminal. Git push still uses Git credentials for the repository URL. After the project is connected, store the project credential:

gitghost-cli project git-credentials
git push origin main

Keep the remote URL clean:

https://gitghost.ai/git/<owner>/<project>.git

Do not put tokens into the remote URL.

What Success Looks Like

After a healthy setup:

Check	Expected Result
gitghost-cli auth status	Shows the terminal is signed in without printing access tokens.
gitghost-cli status	Shows the active project, repository alignment, hook status, project token state, and next steps.
gitghost-cli agent list	Shows supported local agents and whether they are detected.
GitGhost AI project	Shows local-agent session activity, evidence, or approval requests after local agent work.
Git push	Works with a clean https://gitghost.ai/git/<owner>/<project>.git remote after project git-credentials.

Common Policy Block

If the UI shows:

Local agent sync is disabled by project Agent Policy

the project or organization policy must allow local agent sync before GitGhost AI can create a connect code. Ask a project admin to open Project Settings > AI Settings and allow the agent type you plan to connect.

Do not work around a policy block by sharing tokens or connecting a different project. The policy is part of the project review model.

Command Discovery

Use these commands when you or a local agent need to understand the installed CLI:

gitghost-cli --help
gitghost-cli setup --help
gitghost-cli status --json
gitghost-cli agent-help
gitghost-cli agent-help --json

Machine-readable checks are available for scripts and local coding agents:

gitghost-cli status --json
gitghost-cli auth status --json
gitghost-cli project status --json
gitghost-cli agent list --json

These commands report readiness without printing access tokens, refresh tokens, or project tokens.

Normal help is intentionally focused on commands users and coding agents should start with. Use gitghost-cli --help --all or gitghost-cli agent-help --include-internal --json only when debugging installed hook receivers or native transcript sync adapters.

If You Installed It And Nothing Appears

Check these in order:

1. Run gitghost-cli auth status.
2. Run gitghost-cli status.
3. Confirm the project has local agent sync enabled.
4. Confirm you used a project connect code, not the CLI login code.
5. Confirm the local agent was started from the project checkout.
6. Run gitghost-cli agent list to see whether the agent is detected.
7. Open Agent Sessions, AI Activity, and AI Approvals in GitGhost AI.
8. Run gitghost-cli doctor if the project, repository, hook, or credential state is unclear.

Logout

gitghost-cli auth logout

Use gitghost-cli auth logout --all when you want to revoke CLI sessions for your account.

You can also review CLI device sessions from Account Security And OAuth.

Related Guides

• AI chat and agent pairing
• AI sessions and evidence
• AI approvals and guardrails
• Auth, device codes, and OAuth
• Troubleshoot CLI agent connect