AGENTS.md instructions for /Users/gtrrz-victor/wks/cli/cli

Architecture

• CLI built with github.com/spf13/cobra and github.com/charmbracelet/huh

Key Directories

Commands (cmd/)

• entire/: Main CLI entry point. Also home to kubectl-style external-command resolution (entire <name> → entire-<name> on PATH) — see External Commands.
• entire/cli: CLI utilities and helpers (Cobra commands, helpers, group roots)
• entire/cli/commands: actual command implementations
• entire/cli/agent: agent implementations (Claude Code, Gemini CLI, OpenCode, Cursor, Factory AI Droid, Copilot CLI, Pi) - see Agent Integration Checklist and Agent Implementation Guide
• entire/cli/strategy: strategy implementation (manual-commit) - see section below
• entire/cli/checkpoint: checkpoint storage abstractions (ephemeral and persistent)
• entire/cli/session: session state management
• entire/cli/integration_test: integration tests (simulated hooks)

Command Layout

The visible CLI is organized around a set of noun groups plus a small set of top-level verbs. The groups are the canonical home for each verb; legacy top-level shortcuts remain functional but hidden, and emit a deprecation hint pointing at the canonical group form. Newer experimental command families are discoverable through entire labs and may remain hidden from root help while their canonical paths are still runnable.

Lifecycle commands

• session (alias: sessions): list, info, tokens, stop, attach, adopt, resume, current.
• checkpoint (aliases: cp, checkpoints): list, explain, tokens, search, plus the deprecated rewind.
• agent: bare opens the interactive agent selector, plus list, add, remove.
• configure: flags manage non-agent settings (telemetry, git-hook installation mode, strategy options, summary provider).
• auth: login, logout, status, contexts, use, plus token (prints the active control-plane bearer to stdout for scripting/curl).
• doctor: bare runs the scan-and-fix flow, plus trace, logs, bundle.
• org: control-plane organization management — create, list, get, delete.
• project: control-plane project management — create, list, get, delete.
• repo: control-plane repository lifecycle — create, list, get, delete, clone, plus the mirror and visibility subtrees.
• grant: manage access grants and org membership — org, project, and repo each support add / list / remove.

Experimental command families advertised through entire labs:

• tokens: profile (hidden from root help while token diagnostics mature)

Tech Stack

• Language: Go 1.26.x
• Build tool: mise, go modules
• Linting: golangci-lint

Development

Running Tests

1

mise run test

Running Integration Tests

1

mise run test:integration

Running All Tests (CI)

1

mise run test:ci

Code Patterns

Error Handling

Use NewSilentError() when you want to print a custom, user-friendly error message instead of the raw error:

// In a command's RunE function:
if _, err := paths.WorktreeRoot(); err != nil {
    cmd.SilenceUsage = true  // Don't show usage for prerequisite errors
    fmt.Fprintln(cmd.ErrOrStderr(), "Not a git repository. Please run 'entire enable' from within a git repository.")
    return NewSilentError(errors.New("not a git repository"))
}

Logging vs User Output

• Internal/debug logging: Use logging.Debug/Info/Warn/Error(ctx, msg, attrs...) from cmd/entire/cli/logging/. Writes to .entire/logs/.
• User-facing output: Use fmt.Fprint*(cmd.OutOrStdout(), ...) or cmd.ErrOrStderr().

Always use t.Parallel() in tests.

Config/Cache/Keyring Isolation in Tests

Tests must never read or write the developer's real ~/.config/entire.

Spawning subprocesses in tests (TTY detection)

Tests that spawn the real entire or git binary need the child to be non-interactive so prompts don't hang on a developer terminal.

1
2
3
4
5

import "github.com/entireio/cli/cmd/entire/cli/execx"

cmd := execx.NonInteractive(ctx, getTestBinary(), "status")
cmd.Dir = repoDir
out, err := cmd.CombinedOutput()

Control-Plane Core Resolution (which core am I talking to?)

Control-plane commands dial one of three cores: the active context's (coreapi.New), a specific cluster's (coreapi.NewForCluster). To display which core a request uses, ask the client: client.CoreOrigin().

Entire-API Cell Routing (which cell does a data-plane request go to?)

The data plane (entire-api) is deployed per jurisdiction; a repo placement lives in exactly one cell.