CLI Reference
Goga is a command-line tool built with Click for validating and managing CODEMANIFEST-based projects.
This page is the command cross-road: every command of the root goga group, mapped to the functional domain that owns it. The full reference of each command — synopsis, options, behavior, exit codes — lives in its domain's CLI page (under Features, or Configuration for goga config).
Installation
After installation, the goga command is available:
Side-by-side versions
pipx can install additional goga releases under their own command names, each in its own isolated virtualenv — useful for running one release against another before switching:
The suffix is appended to the executable name: the command above installs
goga 2.0 as goga2.0, while the plain goga stays untouched.
goga2.0 --version # the version of that environment
goga --version # the version of your main install
Reinstalling over an existing suffix needs --force. pipx marks
--suffix as experimental and subject to change.
Commands
| Command | Domain | Description |
|---|---|---|
goga init |
Init | Interactive project initialization |
goga install |
Install | Install goga-tool packages into the current interpreter and re-sync connected agents |
goga uninstall |
Install | Remove a goga-tool package from the current interpreter and re-sync connected agents |
goga lint |
Lint | Validate CODEMANIFEST files |
goga build |
Build | Execute a build plan in an isolated container |
goga contract |
Contract | Compare CODEMANIFEST with implementation |
goga config |
Configuration | Display configuration values |
goga schema |
Schema | Generate JSON schema from project cells |
goga connect |
Connect | Install goga skills for AI agents |
goga upgrade |
Upgrade | Upgrade goga and re-sync connected agents |
goga usages |
Usages | Sync cell-level usages from declared git dependencies and check their status against the remote |
goga pipeline |
Pipelines | Run a goga pipeline, or inspect the available ones (--list, --info) |
goga history |
History | Work with the .goga/history/ tree (list, status, path, ensure, prune) |
goga topics |
Topics | Work with the topics of one year (board, create, switch, update, publish, propagate, delete, clear) |
goga tool |
Tools | Dynamic tool package invocation |
goga hooks |
Hooks | Inspect the hooks registered by installed tool packages |
Slash commands in agents
The slash-command form /goga:<command> works in agents that consume the goga command bundle — currently claude, opencode, and qwen (see goga connect). Codex and cursor do not register commands; in those agents invoke the skill directly: goga-<command> (Codex uses the $ prefix — for example, $goga-specify).
Global Options
The root goga command is a Click group. It supports the standard Click --help flag:
All subcommands also accept --help for inline usage information.
The group also carries a global --version / -v flag:
| Option | Description |
|---|---|
--version, -v |
Print the goga version installed on the host and exit |
The flag prints a bare version string (machine-readable, no decorations) to stdout and exits with code 0:
The option belongs to the root group and is processed eagerly, before any subcommand dispatch — it is available on the root invocation only (goga --version), never as a subcommand option. Subcommands with their own same-named option are unaffected: goga install --version <v> still addresses the install command's value option, which the group flag does not intercept.
When the installed version cannot be determined (goga is not installed for the current interpreter, or its metadata is broken), the command fails cleanly: a one-line Error: cannot determine the installed goga version (...) message on stderr, exit code 1, no traceback.
The flag takes no part in the host–image version check performed before container launches — that check is part of goga build and goga pipeline.