# Architecture Source: https://docs.entire.com/agents/agent-integration-protocol/architecture How the Entire CLI discovers and communicates with agent integrations Entire discovers agent integrations through executable naming and `$PATH` lookup: 1. You create an executable named `entire-agent-` 2. Place it anywhere on your `$PATH` 3. The CLI discovers it at startup and registers it as a new agent The integration communicates with the CLI through **subcommands** that read and write JSON over stdin and stdout. Each invocation is stateless. Every subcommand invocation receives these environment variables: | Variable | Description | | - | - | | `ENTIRE_REPO_ROOT` | Absolute path to the git repository root | | `ENTIRE_PROTOCOL_VERSION` | Protocol version (currently `1`) | Entire runs every subcommand from the repository root. The integration follows these conventions: * **Output:** JSON on stdout (unless noted otherwise) * **Errors:** Nonzero exit code and message on stderr * **Stateless:** Each invocation is independent, no persistent connection # Build an Agent Integration Source: https://docs.entire.com/agents/agent-integration-protocol/build-an-agent-integration Use the external-agents agent skill to add support for another coding agent You can build an agent integration when you want Entire to support a coding agent that is not natively supported in the Entire CLI yet. The [external-agents repository](https://github.com/entireio/external-agents) includes an agent skill that does most of the work. The skill researches the target agent. Next, it creates the starter code for the binary and writes tests. Then it writes the code that follows the protocol. You can write an integration in any language. This guide uses the Go version in that repository and its skill. For the protocol itself, see [Architecture](/agents/agent-integration-protocol/architecture), [Commands](/agents/agent-integration-protocol/commands), [Lifecycle](/agents/agent-integration-protocol/lifecycle), and [Data Model](/agents/agent-integration-protocol/data-model). > [!NOTE] > > **Building a private or internal integration?** This guide is the upstream contribution path, which ends in a pull request to `external-agents`. For an integration you won't contribute back, skip the issue and PR steps and follow the protocol reference above. ## Before You Start Open an issue in [`entireio/external-agents`](https://github.com/entireio/external-agents) before writing code. Adding support for a new agent creates an ongoing support commitment, so align with maintainers first. You need: * The target agent CLI installed and authenticated * [The Entire CLI installed](/installation) * [Go](https://go.dev/doc/install) and [mise](https://mise.jdx.dev/getting-started.html) * A target agent with lifecycle hooks or another reliable event mechanism * Readable session or transcript data * A stable session ID ## Clone the Repo ```bash theme={null} git clone https://github.com/entireio/external-agents.git cd external-agents mise trust mise install ``` New integrations live under `agents/entire-agent-`. Each integration is a standalone binary named `entire-agent-`. ## Run the Agent Skill The repo includes an agent skill named `entire-external-agent`, and supported tools discover it automatically with no additional configuration. See the [repo instructions](https://github.com/entireio/external-agents?tab=readme-ov-file#getting-started--zero-setup) for the current supported tools. Run the skill: ```text theme={null} /entire-external-agent ``` When prompted, provide the target agent name and slug. ## What the Skill Does The skill runs three phases: | Phase | What happens | | - | - | | **Research** | Finds the target agent's hooks, session IDs, transcript storage, CLI commands, and capabilities. | | **Scaffold** | Creates the integration structure, protocol stubs, and lifecycle test wiring. | | **Implement** | Uses compliance and lifecycle failures to implement the integration and add tests. | You can also run a single phase when you need to restart or inspect part of the process. ```text theme={null} /entire-external-agent research /entire-external-agent write-tests /entire-external-agent implement ``` ## Reference Examples The [external-agents repository](https://github.com/entireio/external-agents) contains working integrations you can inspect while building your own: | Integration | Target agent | Notes | | - | - | - | | [`entire-agent-amp`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-amp) | Amp | Agent integration with transcript preparation, token calculation, and compact transcript support. | | [`entire-agent-goose`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-goose) | Goose | Agent integration that exports Goose sessions from SQLite-backed storage. | | [`entire-agent-kiro`](https://github.com/entireio/external-agents/tree/main/agents/entire-agent-kiro) | Kiro | Lifecycle hooks and transcript analysis for Kiro sessions. | For a minimal reference implementation outside the main examples repo, see [`roger-roger`](https://github.com/entireio/roger-roger). ## Review the Output When the skill finishes, review: * `agents/entire-agent-/AGENT.md` * `agents/entire-agent-/README.md` * The declared capabilities * Protocol compliance results * Lifecycle test results * Any remaining gaps or local dependencies Treat captured hook payloads and transcript fixtures as ground truth. Documentation can drift. ## Verify Locally Build the binary, put it on your `PATH`, and enable it in a test repository: ```bash theme={null} cd agents/entire-agent- mise run build export PATH="$PWD:$PATH" cd /path/to/test-repo entire enable --agent SLUG ``` Run the target agent and make a small file change. Then check that Entire captured the session: ```bash theme={null} entire status entire checkpoint list entire checkpoint explain CHECKPOINT_ID --short ``` Look for a checkpoint with the expected session, transcript, and modified files. ## Open the PR Reference the approved issue and include: * Agent name and binary name * Declared capabilities * Protocol compliance status * Lifecycle test status * Unit test coverage * Any local dependencies you could not test * Known limitations CI will build the agent and run the shared checks. # Commands Source: https://docs.entire.com/agents/agent-integration-protocol/commands Required commands and optional capabilities for agent integrations Every agent integration must implement these subcommands. ## Required Commands ### `info` Returns metadata and declares which optional capabilities your integration supports. ```bash theme={null} entire-agent-myagent info ``` ```json theme={null} { "protocol_version": 1, "name": "myagent", "type": "MyAgent", "description": "MyAgent - AI-powered code editor", "protected_dirs": [".myagent"], "hook_names": ["session-start", "session-end", "stop"], "capabilities": { "hooks": true, "transcript_analyzer": true, "transcript_preparer": false, "token_calculator": false, "text_generator": false, "hook_response_writer": false, "subagent_aware_extractor": false } } ``` | Field | Description | | - | - | | `protocol_version` | Must match the CLI's expected version (currently `1`) | | `name` | Registry name (must match the `` in the binary name) | | `type` | Display name / type identifier | | `description` | Description for readers | | `protected_dirs` | Directories the CLI should not modify (excluded from checkpoints and diffs) | | `hook_names` | Agent lifecycle hooks this integration handles | | `capabilities` | Object declaring which optional capabilities are supported | ### `detect` Returns whether the agent is available in the current environment. Return `{"present": false}` if the agent's dependencies are not met. The CLI will skip enabling the agent. ```bash theme={null} entire-agent-myagent detect ``` ```json theme={null} {"present": true} ``` ### `get-session-id` Extracts a session ID from a hook input event. **stdin:** [HookInput](/agents/agent-integration-protocol/data-model#hookinput) JSON ```json theme={null} {"session_id": "abc123"} ``` ### `get-session-dir --repo-path ` Returns where agent sessions are stored. ```json theme={null} {"session_dir": "/path/to/sessions"} ``` ### `resolve-session-file --session-dir --session-id ` Resolves the session file path from a session directory and ID. ```json theme={null} {"session_file": "/path/to/session/file.jsonl"} ``` ### `read-session` Reads session data from a hook input event. **stdin:** [HookInput](/agents/agent-integration-protocol/data-model#hookinput) JSON **stdout:** [AgentSession](/agents/agent-integration-protocol/data-model#agentsession) JSON ### `write-session` Persists session data to disk. The integration chooses the storage location and format. **stdin:** [AgentSession](/agents/agent-integration-protocol/data-model#agentsession) JSON Exit `0` on success. ### `read-transcript --session-ref ` Reads a transcript file and returns its raw bytes on stdout. ### `chunk-transcript --max-size ` Splits a transcript (raw bytes on stdin) into chunks. ```json theme={null} {"chunks": ["", "..."]} ``` ### `reassemble-transcript` Reassembles chunks into a transcript when `entire session resume` restores stored session data. **stdin:** ```json theme={null} {"chunks": ["", "..."]} ``` **stdout:** Raw transcript bytes. ### `format-resume-command --session-id ` Returns the command a user would run to resume a session. ```json theme={null} {"command": "myagent --resume abc123"} ``` ## Optional Capabilities Set capabilities to `true` in your `info` response to enable these. The CLI will never call subcommands for capabilities you don't declare. ### `hooks` Manage agent lifecycle hooks for Entire integration. | Subcommand | Description | | - | - | | `parse-hook --hook ` | Parse a raw hook payload (stdin) into an [Event](/agents/agent-integration-protocol/data-model#event). Return `null` if not relevant. | | `install-hooks [--local-dev] [--force]` | Install hooks. `--local-dev` installs hooks pointing to a local development build. `--force` overwrites existing hook files. Returns `{"hooks_installed": 3}`. | | `uninstall-hooks` | Remove installed hooks. Exit `0` on success. | | `are-hooks-installed` | Check hook status. Returns `{"installed": true}`. | ### `transcript_analyzer` Extract data from agent transcripts. | Subcommand | Description | | - | - | | `get-transcript-position --path ` | Returns `{"position": 12345}` (byte offset). | | `extract-modified-files --path --offset ` | Returns `{"files": [...], "current_position": 12345}`. | | `extract-prompts --session-ref --offset ` | Returns `{"prompts": ["prompt text", ...]}`. | | `extract-summary --session-ref ` | Returns `{"summary": "...", "has_summary": true}`. | ### `transcript_preparer` | Subcommand | Description | | - | - | | `prepare-transcript --session-ref ` | Prepare a transcript file. Exit `0` on success. | ### `token_calculator` | Subcommand | Description | | - | - | | `calculate-tokens --offset ` | Calculate token usage from transcript bytes (stdin). `--offset` is the byte offset into the transcript to start counting from. | Output: ```json theme={null} { "input_tokens": 1500, "output_tokens": 500, "cache_creation_tokens": 0, "cache_read_tokens": 200, "api_call_count": 3 } ``` You must return `input_tokens` and `output_tokens`. The CLI uses `0` for fields you omit. ### `text_generator` | Subcommand | Description | | - | - | | `generate-text --model ` | Generate text from a prompt (stdin). Returns `{"text": "..."}`. | ### `hook_response_writer` | Subcommand | Description | | - | - | | `write-hook-response --message ` | Write a message in the agent's native hook format (stdout). | ### `subagent_aware_extractor` For agents that spawn subagents. | Subcommand | Description | | - | - | | `extract-all-modified-files --offset --subagents-dir ` | Extract modified files from main + subagent transcripts (stdin: main transcript). Returns `{"files": [...]}`. | | `calculate-total-tokens --offset --subagents-dir ` | Calculate total tokens across main + subagent transcripts (stdin: main transcript). Same format as `calculate-tokens`, with optional `subagent_tokens` nested object. | # Data Model Source: https://docs.entire.com/agents/agent-integration-protocol/data-model Data types exchanged between the Entire CLI and agent integrations ## HookInput Entire passes `HookInput` via stdin to `get-session-id` and `read-session`. ```json theme={null} { "hook_type": "stop", "session_id": "abc123", "session_ref": "/path/to/transcript.jsonl", "timestamp": "2026-01-13T12:00:00Z", "user_prompt": "Fix the login bug", "tool_name": "Write", "tool_use_id": "toolu_abc123", "tool_input": {"path": "/src/main.go"}, "raw_data": {} } ``` | Field | Type | Required | Description | | - | - | - | - | | `hook_type` | string | Yes | `session_start`, `session_end`, `user_prompt_submit`, `stop`, `pre_tool_use`, `post_tool_use` | | `session_id` | string | Yes | Agent session identifier | | `session_ref` | string | Yes | Session reference specific to the agent, typically a file path | | `timestamp` | string | Yes | RFC 3339 timestamp | | `user_prompt` | string | No | User's prompt text | | `tool_name` | string | No | Tool name (from tool use hooks) | | `tool_use_id` | string | No | Tool invocation ID | | `tool_input` | object | No | Raw tool input JSON | | `raw_data` | object | No | Extension data specific to the agent | ## AgentSession Entire passes `AgentSession` to `write-session` and receives it from `read-session`. ```json theme={null} { "session_id": "abc123", "agent_name": "myagent", "repo_path": "/path/to/repo", "session_ref": "/path/to/transcript.jsonl", "start_time": "2026-01-13T12:00:00Z", "native_data": null, "modified_files": ["src/main.go"], "new_files": [], "deleted_files": [] } ``` | Field | Type | Description | | - | - | - | | `session_id` | string | Agent session identifier | | `agent_name` | string | Agent registry name | | `repo_path` | string | Absolute path to the repository | | `session_ref` | string | Path to session in agent's storage | | `start_time` | string | RFC 3339 timestamp | | `native_data` | bytes/null | Opaque session content in agent's native format | | `modified_files` | string\[] | Files modified during the session | | `new_files` | string\[] | Files created during the session | | `deleted_files` | string\[] | Files deleted during the session | ## Event The `parse-hook` subcommand returns this normalized lifecycle event. ```json theme={null} { "type": 3, "session_id": "abc123", "session_ref": "/path/to/transcript.jsonl", "prompt": "Fix the login bug", "model": "claude-sonnet-4-20250514", "timestamp": "2026-01-13T12:00:00Z" } ``` **Event types:** | Value | Name | Description | | - | - | - | | 1 | SessionStart | Agent began a session | | 2 | TurnStart | User submitted a prompt | | 3 | TurnEnd | Agent finished responding | | 4 | Compaction | Agent compressed its context window, which triggers a save and offset reset | | 5 | SessionEnd | Session ended | | 6 | SubagentStart | Agent spawned a subagent | | 7 | SubagentEnd | Subagent completed its task | **Optional event fields:** `previous_session_id`, `session_ref`, `prompt`, `model`, `timestamp`, `tool_use_id`, `subagent_id`, `tool_input`, `subagent_type`, `task_description`, `response_message`, `metadata`. You must provide `type` and `session_id`. # Lifecycle Source: https://docs.entire.com/agents/agent-integration-protocol/lifecycle When the Entire CLI calls each agent integration command The CLI calls integration subcommands in five phases. ## Phase 1: Discovery (CLI Startup) Every time the CLI starts, it scans `$PATH` for binaries matching `entire-agent-`. 1. **`info`**: The CLI calls this command once per discovered binary. It reads your metadata, validates the protocol version, and registers the agent. If this fails, the CLI skips the agent. ## Phase 2: Enable (`entire enable`) When a user enables your agent for a repository: 1. **`detect`**: The CLI calls this command to check whether your agent is available in the current environment. 2. **`install-hooks [--local-dev] [--force]`**: The CLI calls this command to install your hooks into the agent, such as by writing hook configuration files. It calls this command only when you declare the `hooks` capability. ## Phase 3: Agent Session (Hooks Firing) After you enable the agent, its hooks fire during normal usage and the CLI processes them. This phase requires the `hooks` capability. Agents that don't declare it won't participate in the hook lifecycle. Every hook invocation follows this flow: ``` Hook fires → parse-hook normalizes → CLI dispatches Event by type ``` 1. **`parse-hook --hook `**: The CLI calls this command on every hook invocation with the raw payload on stdin. Return a normalized [Event](/agents/agent-integration-protocol/data-model#event), or `null` if the hook has no lifecycle significance and the CLI should take no action. The CLI then routes the event by type: ### SessionStart (Type 1) The agent fires this event when it begins a new session. 1. **`get-session-id`**: Extract the session ID from the hook input (stdin). 2. **`get-session-dir --repo-path `**: Return where sessions are stored. 3. **`resolve-session-file --session-dir --session-id `**: Resolve the session file path. 4. **`read-session`**: Read existing session data (stdin: [HookInput](/agents/agent-integration-protocol/data-model#hookinput)). 5. **`write-session`**: Persist updated session data. 6. **`write-hook-response --message `**: *(optional, if `hook_response_writer` capability)* Write a startup message in your agent's native format. ### TurnStart (Type 2) The agent fires this event when the user submits a new prompt. 1. **`extract-modified-files --path --offset `**: *(if `transcript_analyzer` capability)* Extract files changed since last checkpoint. 2. The CLI creates a git checkpoint of the current state. ### TurnEnd (Type 3) The agent fires this event when it finishes responding. 1. **`prepare-transcript --session-ref `**: *(if `transcript_preparer` capability)* Prepare the transcript. 2. **`read-transcript --session-ref `**: Read the raw transcript bytes. 3. **`chunk-transcript --max-size `**: Split large transcripts into storable chunks. 4. **`get-transcript-position --path `**: *(if `transcript_analyzer` capability)* Get the current byte offset. 5. **`extract-modified-files --path --offset `**: *(if `transcript_analyzer` capability)* Extract newly modified files. 6. **`calculate-tokens --offset `**: *(if `token_calculator` capability)* Calculate token usage. 7. The CLI stores a checkpoint in git history. ### Compaction (Type 4) The agent fires this event when it compresses its context window. The CLI follows the same flow as **TurnEnd** and saves the checkpoint before resetting the offset. ### SessionEnd (Type 5) The agent fires this event when the session ends. The CLI creates a final checkpoint and cleans up session state. ### SubagentStart / SubagentEnd (Types 6 and 7) The agent fires these events when it spawns or completes a subagent. If you declare the `subagent_aware_extractor` capability, the CLI calls: * **`extract-all-modified-files --offset --subagents-dir `** * **`calculate-total-tokens --offset --subagents-dir `** ## Phase 4: User Commands Some CLI commands invoke your integration outside the hook flow: | Command | Subcommands called | | - | - | | `entire session resume` | `read-transcript`, `reassemble-transcript`, `extract-modified-files`, `format-resume-command` | | `entire status` | `get-transcript-position` | ## Phase 5: Disable (`entire disable --uninstall`) 1. **`uninstall-hooks`**: The CLI calls this command to remove your installed hooks when you declare the `hooks` capability. ## Error Handling * **Timeout:** Each subcommand has a default timeout of 30 seconds. * **Output limits:** The CLI caps stdout and stderr at 10 MB each. Account for this limit when you implement `read-transcript` for large sessions. * **No retries:** The CLI does not retry failed subcommand calls. It treats a nonzero exit code with a message on stderr as a failure. * **Graceful degradation:** If `parse-hook` returns `null`, the CLI takes no action. If the repo has Entire disabled, hooks exit silently. # Agent Integration Protocol Source: https://docs.entire.com/agents/agent-integration-protocol/overview Add support for an AI coding agent that Entire does not ship with If your agent is not listed in our [native agent integrations](/agents/overview), you can still integrate it with Entire. This can be done with the Agent Integration Protocol by building an `entire-agent-` executable and putting it on your `$PATH`. Entire discovers it there and registers it as an agent. ## Add an Agent Integration After you put the executable on your `$PATH`, install its hooks in an existing Entire repository: ```bash theme={null} entire agent add NAME ``` During initial setup, select it with: ```bash theme={null} entire enable --agent NAME ``` See [`entire agent add`](/cli-reference/agent#agent-add) and [`entire enable --agent`](/cli-reference/enable) for their flags and setup behavior. > [!NOTE] > > Selecting a discovered agent with `entire agent add` or `entire enable --agent` sets `external_agents` to `true`. If you install an integration executable after setup, run `entire agent add NAME` or add `"external_agents": true` to `.entire/settings.json`. The setting key keeps its original name. > [!WARNING] > > Agent integrations receive repository paths and session data, and they run with the same filesystem access as the Entire CLI. Only install integrations you trust. ## Protocol Reference > **[Build an Agent Integration](/agents/agent-integration-protocol/build-an-agent-integration)** > > Scaffold an executable and implement the protocol with working examples. > **[Architecture](/agents/agent-integration-protocol/architecture)** > > See how the CLI discovers an integration and invokes it. > **[Lifecycle](/agents/agent-integration-protocol/lifecycle)** > > Follow the CLI calls through discovery, setup, sessions, and shutdown. > **[Commands](/agents/agent-integration-protocol/commands)** > > Implement each subcommand, input, and output. > **[Data Model](/agents/agent-integration-protocol/data-model)** > > Use the JSON shapes that the protocol exchanges. # Antigravity Source: https://docs.entire.com/agents/antigravity Capture Antigravity CLI prompts, session transcripts, recorded file changes, and token usage with Entire Entire captures Antigravity CLI prompts, session transcripts, recorded file changes, and token usage, then links each session to its Git commits. ## Before You Start Install and authenticate [Antigravity CLI](https://antigravity.google/blog/introducing-google-antigravity-cli), and [install or update Entire](/installation). Run `entire agent list` to make sure your installed build includes `antigravity`. ## Add Antigravity From a repository where you already enabled Entire, run: ```bash theme={null} entire agent add antigravity agy ``` If you have not enabled Entire in the repository, run: ```bash theme={null} entire enable --agent antigravity agy ``` Work and commit as usual. Entire captures the session in the background. ## Hooks and Transcripts Entire manages the `entire` entry in `.agents/hooks.json` and preserves other entries. The hooks capture turn boundaries and file changes. Entire reads prompts, responses, and tool calls from Antigravity's full JSONL transcript. ## Token Usage Antigravity supplies token usage through its title feed rather than its transcripts. When `agy` is on your `PATH`, Entire setup configures the `title` command in `~/.gemini/antigravity-cli/settings.json` to pass that feed through `entire hooks antigravity title-tee`. Entire preserves an existing title command by wrapping it. Token capture depends on this setting. Run `entire doctor` to check it, or rerun `entire agent add antigravity` to repair the setup. Removing the integration with `entire agent remove antigravity` also removes Entire's title wrapper and restores the previous command when present. ## Verify Capture Check tracking and the integration's configuration: ```bash theme={null} entire status entire doctor ``` See [Set Up an Agent](/agents/setup#verify-capture) to verify checkpoints and troubleshoot capture. ## Limitations * Entire does not display a tracking banner inside Antigravity. Use `entire status` to check capture. * Entire does not yet support Antigravity subagent lifecycle hooks or attach subagent sessions to the parent checkpoint. Antigravity can still run subagents as separate conversations. ## Resume and Import To resume a recorded session on a branch, run: ```bash theme={null} entire session resume BRANCH ``` Entire checks out the branch and restores the recorded session log when needed. In an interactive terminal, it asks whether to start the agent. Otherwise, it prints the resume command: ```bash theme={null} agy --conversation SESSION_ID ``` Entire keeps an existing local session log by default. See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and checkout behavior. # Claude Code Source: https://docs.entire.com/agents/claude-code Capture Claude Code transcripts, file changes, tool calls, tokens, and subagent sessions with Entire Claude Code is Entire's default integration. It captures the main session and nested subagent sessions. Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps. ## Add Claude Code ```bash theme={null} entire agent add claude-code claude ``` Entire adds lifecycle hooks to `.claude/settings.json` and preserves unrelated Claude Code settings. The hooks capture session boundaries, prompts, completed turns, and task events. Entire reads the full conversation, file changes, tool calls, and token usage from Claude Code's JSONL transcripts. ## Subagent Capture Claude Code exposes task lifecycle events and separate subagent transcripts. Entire records each task against the parent session, attributes its files and tokens to that session, and materializes its transcript into the parent's next checkpoint. The checkpoint then carries the subagent's work on its own, without reading back into Claude Code's transcript directory. Entire records any subagent that changed files. It also keeps read-only subagents, such as reviewers and search agents, when you launch them with `run_in_background`. A background launch defers capture to subagent stop, which is where Entire materializes a transcript even though the subagent wrote nothing. Foreground subagents complete at launch time, so a read-only one there leaves no record. Among the built-in integrations, Claude Code is the one that reaches read-only subagents. ## Resume and Import `entire session resume BRANCH` restores the recorded session data when needed and prints a command in this form: ```bash theme={null} claude -r SESSION_ID ``` Entire can also import existing Claude Code transcripts from the previous 30 days as read-only checkpoints. See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior. # Codex Source: https://docs.entire.com/agents/codex Capture Codex transcripts, file changes, tokens, and subagent sessions with Entire The Codex integration uses Codex's project-level hook system. Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps. ## Add Codex ```bash theme={null} entire agent add codex codex ``` Entire writes `.codex/hooks.json`. Codex enables hooks by default beginning with version 0.124.0, so Entire does not create `.codex/config.toml` or set `codex_hooks = true`. The hooks capture session boundaries, prompts, completed turns, file-changing tool calls, and subagent events. Entire reads the full conversation and token usage from Codex rollout files under `~/.codex/` or `CODEX_HOME`. ## Limitations Ephemeral Codex runs may not provide a transcript path. Entire can process their hook events, but it cannot attach a full transcript without the rollout file. Entire records the subagents that changed files, materializes their transcripts into the parent's next checkpoint, and attributes their files to the parent session. It skips a subagent that wrote nothing, and it does not yet roll subagent tokens up into the parent session's totals. ## Resume and Import `entire session resume BRANCH` restores the recorded session data when needed and prints: ```bash theme={null} codex resume SESSION_ID ``` Entire can import existing Codex transcripts from the previous 30 days as read-only checkpoints. See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior. # Copilot CLI Source: https://docs.entire.com/agents/copilot-cli Capture Copilot CLI transcripts, file changes, tool calls, and token usage with Entire The Copilot CLI integration uses GitHub Copilot CLI's project-level hooks. Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps. ## Add Copilot CLI ```bash theme={null} entire agent add copilot-cli copilot ``` Entire writes its hook configuration to `.github/hooks/entire.json`. The hooks capture session boundaries, prompts, completed turns, tool activity, errors, and subagent completion. Entire reads the full conversation, file changes, and tool calls from Copilot CLI's JSONL transcript. ## Limitations Copilot CLI reports aggregate token usage when the session ends. Token totals may remain incomplete during an active session. Copilot CLI provides a subagent stop hook without a corresponding start hook. Entire records the completed subagent operation and uses the parent session's pre-prompt state instead of a subagent-specific pre-task snapshot. ## Resume and Import `entire session resume BRANCH` restores the recorded session data when needed and prints: ```bash theme={null} copilot --resume SESSION_ID ``` Entire can import existing Copilot CLI transcripts from the previous 30 days as read-only checkpoints. See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior. # Cursor Source: https://docs.entire.com/agents/cursor Capture Cursor IDE and CLI transcripts, file changes, tool calls, and subagent sessions with Entire The Cursor integration supports Cursor IDE and Cursor CLI through project-level hooks. Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps. ## Add Cursor ```bash theme={null} entire agent add cursor cursor ``` Use `agent` instead of `cursor` to start Cursor CLI. Entire writes `.cursor/hooks.json`. The hooks capture session boundaries, prompts, completed turns, compaction, and subagent events. Entire reads the conversation and tool calls from Cursor's JSONL transcript. It identifies changed files from `Write` and `StrReplace` calls, hook payloads, and Git status. ## Limitations Cursor transcripts do not provide token usage. Cursor also does not expose a command that resumes the recorded native session, so `entire session resume` opens the project without restoring the prior Cursor conversation. Cursor CLI hook payloads may omit the transcript path. Entire resolves the transcript from Cursor's project session directory when this happens. Entire records the subagents that changed files, materializes their transcripts into the parent's next checkpoint, and attributes their files to the parent session. It skips a subagent that wrote nothing. ## Import Entire can import existing Cursor transcripts from the previous 30 days as read-only checkpoints. # Factory Source: https://docs.entire.com/agents/factory-droid Capture Factory Droid transcripts, file changes, tool calls, tokens, and subagent sessions with Entire The Factory integration uses Factory Droid's project-level hooks. Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps. ## Add Factory ```bash theme={null} entire agent add factoryai-droid droid ``` Entire adds lifecycle hooks to `.factory/settings.json` and preserves unrelated Factory settings. The hooks capture session boundaries, prompts, completed turns, compaction, and task tool calls. Entire reads the full conversation, file changes, tool calls, and token usage from Factory's JSONL transcripts. ## Subagent Capture Factory exposes task tool events, and its Workers run as sessions of their own. Entire attributes a Worker's turn to the parent task invocation instead of minting a separate top-level session, rolls its files and tokens onto the parent session, and materializes its transcript into the parent's next checkpoint. Entire records a Worker that changed files, along with its transcript and its tokens. Capture keys on those file changes, so a read-only Worker leaves no record. ## Resume and Import `entire session resume BRANCH` restores the recorded session data when needed and prints: ```bash theme={null} droid --session-id SESSION_ID ``` Entire can import existing Factory transcripts from the previous 30 days as read-only checkpoints. See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior. # OpenCode Source: https://docs.entire.com/agents/opencode Capture OpenCode transcripts, file changes, tool calls, and token usage with Entire The OpenCode integration uses a project-level TypeScript plugin. Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps. ## Add OpenCode ```bash theme={null} entire agent add opencode opencode ``` Entire writes `.opencode/plugins/entire.ts`. The plugin captures session and turn events, then uses `opencode export` to materialize the full conversation, file changes, tool calls, and token usage. OpenCode supports commits before a turn ends. Entire refreshes the exported transcript so a checkpoint created mid-turn includes the agent activity available at that point. ## Limitations OpenCode does not expose subagent lifecycle events. Entire captures the main session. `entire import` cannot import existing OpenCode sessions. ## Resume `entire session resume BRANCH` restores the recorded session data when needed and prints: ```bash theme={null} opencode -s SESSION_ID ``` See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior. # Agent Integrations Source: https://docs.entire.com/agents/overview Compare Entire's built-in AI coding agent integrations and their capabilities Entire uses agent hooks to capture AI coding sessions and connect them to Git commits. Claude Code is the default integration. Choose another integration with its agent name. ## Compare Built-In Integrations
Agent and CLI Name Hooks Transcript Tokens Subagents Resume Import
[Antigravity CLI](/agents/antigravity)\ `antigravity` NativeFullTitle feedNoYesNo
[Claude Code](/agents/claude-code)\ `claude-code` NativeFullYesAllYesYes
[Codex](/agents/codex)\ `codex` NativeFullYesFile changesYesYes
[Copilot CLI](/agents/copilot-cli)\ `copilot-cli` NativeFullAfter sessionPartialYesYes
[Cursor](/agents/cursor)\ `cursor` NativeFullNoFile changesNoYes
[Factory](/agents/factory-droid)\ `factoryai-droid` NativeFullYesFile changesYesYes
[OpenCode](/agents/opencode)\ `opencode` PluginFullYesNoYesNo
[Pi](/agents/pi)\ `pi` ExtensionFullYesNoYesYes
The Subagents column describes which subagents reach a checkpoint. "All" means Entire records every subagent that changed files, plus read-only subagents such as reviewers and search agents when you launch them with `run_in_background`. "File changes" means Entire records the subagents that changed files and skips a subagent that wrote nothing. "Partial" means Copilot CLI provides a subagent stop event without a corresponding start event. Entire notes that the subagent completed, but it cannot take a subagent-specific pre-task snapshot or attach the subagent's transcript. Claude Code and Factory roll subagent tokens up into the parent session's totals. Codex and Cursor store the transcripts without aggregating their tokens yet. Whichever agent records the subagent, the parent's next checkpoint materializes the subagent's transcript alongside its own, so the checkpoint carries that work without reading back into the agent's transcript directory. entire.com does not browse these records yet. > **[Set Up an Agent](/agents/setup)** > > Install hooks, add CLI-managed skills, verify capture, and troubleshoot shared setup. > **[Agent Integration Protocol](/agents/agent-integration-protocol/overview)** > > Add an agent Entire does not ship with by writing an `entire-agent-` executable. CLI plugins use `entire-` instead and add commands rather than agent support. See working integrations at [github.com/entireio/external-agents](https://github.com/entireio/external-agents). ## Agent Integrations Entire can discover agent integrations from executables named `entire-agent-` on your `$PATH`. Enable external agent discovery with the `external_agents` setting, then use the discovered name with commands such as `entire enable --agent `. Agent integrations declare their own hooks and capabilities, so their support varies by implementation. See the [Agent Integration Protocol](/agents/agent-integration-protocol/overview) for the protocol, setup, and security model. ## MCP Hosts [`entire mcp`](/cli-reference/mcp) runs a stdio MCP server that exposes Entire's `agent_help` and `entire_status` tools. It gives an MCP host current CLI usage and repository status. It does not replace lifecycle hooks for session capture. # Pi Source: https://docs.entire.com/agents/pi Capture Pi transcripts, file changes, tool calls, and token usage with Entire The Pi integration uses a project-level TypeScript extension. Follow [Set Up an Agent](/agents/setup) for shared installation, verification, and troubleshooting steps. ## Add Pi ```bash theme={null} entire agent add pi pi ``` Entire writes `.pi/extensions/entire/index.ts`. The extension captures session boundaries, prompts, and completed turns. Entire reads the full conversation, file changes, tool calls, and token usage from Pi's JSONL transcript. [Enable Entire for Pi](https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/89f76783a7be608b7c7c646d8dd9ea1f/iframe?loop=true\&autoplay=true\&poster=https%3A%2F%2Fcustomer-0x5hsk8lh27fm00g.cloudflarestream.com%2F89f76783a7be608b7c7c646d8dd9ea1f%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600) ## Limitations Pi does not expose a subagent transcript tree. Entire captures the main session. Pi's `write` and `edit` tools provide file paths in the transcript; files changed through shell commands remain visible in the Git diff but may not appear as transcript tool edits. ## Resume and Import `entire session resume BRANCH` restores the recorded session data when needed and prints: ```bash theme={null} pi --session SESSION_ID ``` Entire can import existing Pi transcripts from the previous 30 days as read-only checkpoints. See the [`session resume` command reference](/cli-reference/session#session-resume) for flags and additional behavior. # Set Up an Agent Source: https://docs.entire.com/agents/setup Install, verify, update, and remove Entire agent hooks Entire installs repository-level hooks for each AI coding agent you use. Agent hooks capture session events, while Entire's Git hooks connect the captured session to commits. ## Before You Start Install the [Entire CLI](/installation) and your preferred [agent integration](/agents/overview). Run these commands from a Git repository after you enable Entire. ## Install Agent Hooks Pass the integration's agent name to `entire agent add`: ```bash theme={null} entire agent add AGENT_NAME ``` For example: ```bash theme={null} entire agent add codex ``` You can install hooks for more than one agent in the same repository. Each integration keeps its configuration in the agent's project directory. During initial Entire setup, select an agent with: ```bash theme={null} entire enable --agent codex ``` ## Agent Integrations An agent integration adds support for a coding agent through an executable named `entire-agent-`. A CLI plugin uses `entire-` and adds a command instead. Add the agent integration executable to your `$PATH` and enable discovery in `.entire/settings.json`: ```json .entire/settings.json theme={null} { "external_agents": true } ``` Entire includes discovered integrations in `entire agent list`. During setup, pass the external agent's name without the `entire-agent-` prefix: ```bash theme={null} entire enable --agent AGENT_NAME ``` See the [Agent Integration Protocol](/agents/agent-integration-protocol/overview) for the protocol and its security considerations. ## Install CLI-Managed Skills `entire agent add` can also install two repository-level skills: ```bash theme={null} entire agent add codex --agent-help-skill --search-skill ``` | Flag | Installs | | - | - | | `--agent-help-skill` | A skill that directs the agent to `entire agent-help` for usage that matches the installed CLI | | `--search-skill` | A skill that helps the agent run `entire search --json` | These flags install the CLI-managed helpers. See [Install Skills](/learn/skills-overview#install-skills) for the Entire Skills collection. ## Hook Locations | Agent | Project Configuration | | - | - | | [Antigravity CLI](/agents/antigravity) | `.agents/hooks.json` | | Claude Code | `.claude/settings.json` | | Codex | `.codex/hooks.json` | | Copilot CLI | `.github/hooks/entire.json` | | Cursor | `.cursor/hooks.json` | | Factory | `.factory/settings.json` | | OpenCode | `.opencode/plugins/entire.ts` | | Pi | `.pi/extensions/entire/index.ts` | Entire preserves unrelated configuration when it adds JSON hooks. OpenCode and Pi use generated TypeScript files that Entire can reinstall when their templates change. ## Verify Capture List the installed integrations and inspect the repository: ```bash theme={null} entire agent list entire status --detailed ``` Start a new agent session from the repository after installing hooks. Existing agent processes do not load hooks added after they started. Commit a file change to create a checkpoint, then inspect it: ```bash theme={null} git add . git commit -m "Describe the change" entire checkpoint list ``` See [Session Storage](/guides/checkpoints/checkpoint-storage) for where Entire writes checkpoint data. ## Reinstall or Remove Hooks Reinstall missing, stale, or modified hooks with: ```bash theme={null} entire agent add AGENT_NAME --force ``` Remove Entire's hooks for one integration with: ```bash theme={null} entire agent remove AGENT_NAME ``` Removing one integration leaves other agent hooks and Entire's Git hooks in place. ## Troubleshoot Capture Run `entire doctor` when `entire status --detailed` does not show a session you started. Confirm that the integration's configuration file exists, restart the agent, and run it from inside the repository. Each agent page documents limitations on transcript capture, token usage, subagent capture, session resume, and transcript import. Use the [capability matrix](/agents/overview#compare-built-in-integrations) to find the relevant page. # Billing Source: https://docs.entire.com/billing Manage prepaid Agent usage credits, free trials, payment methods, and automatic top-ups. Entire bills only for Agent usage, using prepaid usage credits. You can continue using other features for free. Charges depend on the AI model tokens your Agents use. Add credit manually or enable automatic top-up to keep your Agents running. ## How Billing Works 1. **Free trial:** Each billing account receives a one-time trial credit when you set up billing or a Agents run starts, whichever happens first. 2. **Usage:** Each time your Agents run, the cost of their model tokens is deducted from your credit balance. 3. **Add credit:** When your trial credit is used up, add a card or pay with Link to buy credit. You can still use other features and Entire's preset runners. 4. **Automatic top-up (optional):** Entire buys more credit when your balance falls below a threshold you choose. 5. **Zero balance:** If your balance reaches \$0, Agents stop until you add more credit. ## Billing Accounts Each personal account and organization is billed separately and has its own credit balance, trial, payment method, and invoices. Agents usage is billed to the account or organization that owns the repository. | Billing account | Who can manage billing | | - | - | | Personal account | The account owner | | Entire organization | Organization admins | | GitHub organization | Admins of the organization on GitHub | For GitHub organizations, Entire verifies admin status with GitHub. Removing someone as a GitHub admin also removes their access to the organization's billing in Entire. ## Free Trial Every billing account receives a one-time trial credit of \*\*$100**. The trial ends after $100 of usage or 90 days after it starts, whichever happens first. The trial credit is granted when either of these happens first: * You set up billing in your account or organization settings. * A Agents run starts for the account or organization. Trial credit does not require a card. It is granted once per billing account, does not reset, and expires 90 days after it is granted. It has no cash value and cannot be transferred. ## Add Credit You can add credit at any time. Once your trial is used up, adding a payment method and buying credit happens in a single flow. **1. Open Billing** Open **Account > Billing** for your personal account or organization. **2. Set Up Billing or Buy Credit** Select **Set up billing** if you haven't added a payment method, or **Buy credit** if billing is already set up. **3. Confirm Your Purchase** Add your credit card details or pay through your Link account, then confirm the purchase. [Set up billing and buy Agents usage credit](https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/9a70a48180156f10cca782b2b2c60f81/iframe) Credit is available immediately and expires 365 days after purchase. Stopped Agents resume automatically when you add credit. ### Update Your Payment Method Open **Account > Billing** and select **Manage card and billing details**. This opens a Stripe-hosted page and returns you to Entire when you're done. ![Account Billing page with Manage card and billing details highlighted under Payment method](https://mintcdn.com/entire/iIWTZ-0P0DyT90Aw/images/billing-payment-method.png?fit=max\&auto=format\&n=iIWTZ-0P0DyT90Aw\&q=85\&s=c236c4896affed114e9e69e6a79e7ec7) ## Automatic Top-Up Automatic top-up buys credit when your balance falls below a threshold, so Agents aren't interrupted. It's off by default. > [!NOTE] > > Automatic top-up is available only after you add a payment method. To turn it on: 1. Open **Account > Billing**. 2. Turn on **Automatic top-up**. 3. Set the threshold balance and the target balance to top up to. By default, Entire tops up to $50 when your balance falls below $10. 4. Save your changes. ![Account Billing page with the Automatic top-up section and its toggle highlighted](https://mintcdn.com/entire/iIWTZ-0P0DyT90Aw/images/billing-automatic-top-up.png?fit=max\&auto=format\&n=iIWTZ-0P0DyT90Aw\&q=85\&s=b44bde3d4774248e692e2f8c53a1fb3a) If a top-up payment fails, Agents stop until the payment succeeds or you add credit manually. ## Models and Pricing Entire offers the following models for your Agents. All prices are **USD per million tokens**, verified against official provider documentation on **October 25, 2026**. Tables show standard API rates for global processing; prompt-length exceptions are listed below. **Input** means uncached input. **Cache read** is the price for reusing cached input, and **cache write** is the price for storing input for later reuse. The write columns show different cache lifetimes. ### Anthropic | Model | Input | Output | Cache read | Cache write (5 min) | Cache write (1 hour) | | - | - | - | - | - | - | | Claude Opus 5.5 (default) | \$4.00 | \$20.00 | \$0.20 | \$5.00 | \$8.00 | | Claude Opus 5 | \$5.00 | \$25.00 | \$0.50 | \$6.25 | \$10.00 | | Claude Sonnet 5.5 | \$2.00 | \$10.00 | \$0.10 | \$2.50 | \$4.00 | | Claude Sonnet 5 | \$2.00 | \$10.00 | \$0.20 | \$2.50 | \$4.00 | | Claude Haiku 5.5 (up to 100,000 prompt tokens) | \$0.10 | \$0.50 | \$0.01 | \$0.125 | \$0.20 | | Claude Haiku 5.5 (over 100,000 prompt tokens) | \$0.50 | \$2.50 | \$0.05 | \$0.625 | \$1.00 | Haiku 5.5 counts all input tokens, including cache reads and writes, toward the 100,000-token threshold. A request above that threshold uses the higher rates for the full request. The other Claude models listed here keep standard token rates across their context windows. Anthropic's default cache lifetime is 5 minutes; 1-hour writes cost more. Reusing a cached prefix refreshes its lifetime at the cache-read rate. ### OpenAI | Model | Input | Output | Cache read | Cache write (30 min) | Cache write (12 hours) | | - | - | - | - | - | - | | GPT-6 Astra | \$10.00 | \$50.00 | \$1.00 | \$12.50 | \$25.00 | | GPT-5.6 Sol | \$4.00 | \$20.00 | \$0.40 | \$5.00 | \$10.00 | | GPT-6.1 Sol (default) | \$2.00 | \$10.00 | \$0.10 | \$2.50 | \$5.00 | | GPT-6 Sol | \$2.00 | \$10.00 | \$0.20 | \$2.50 | \$5.00 | | GPT-5.6 Luna | \$0.20 | \$1.20 | \$0.02 | \$0.25 | \$0.50 | | GPT-6 Luna | \$0.10 | \$0.50 | \$0.01 | \$0.125 | \$0.25 | For GPT-5.6 and later, the default cache-write lifetime is 30 minutes at 1.25× the uncached input rate. The Responses API also supports 12-hour writes at 2.5× input. The 12-hour prices for GPT-6 Sol and GPT-5.6 Luna above are calculated using that published multiplier. These are total write prices, not additional fees on top of uncached input. Cache-read prices are the same for both lifetimes. For all OpenAI models listed here, requests with more than 272,000 input tokens cost 2× the input rate and 1.5× the output rate for the full request. GPT-6 models also double cache-read and cache-write rates at that threshold. Agents usage is priced at the model provider's published rates. Rates update automatically when providers change their prices. Regional processing or faster processing modes can have different prices. The cache duration used by a model call determines which write rate applies. Larger models generally cost more per run than smaller ones. The total cost also depends on how many tokens a run uses and how much input is reused from cache. ## When Your Balance Reaches Zero When your balance reaches \$0, Agents stop for that billing account in every region, and new runs do not start. Agents resume automatically once credit is added through a purchase or a successful top-up. ## Payments and Invoices Purchases and top-ups are charged to your payment method immediately through Stripe. You also receive a monthly usage invoice. It only shows an amount due if usage continued briefly after your credits reached zero and before your Agents stopped. ## Defaults and Limits | Setting | Value | | - | - | | Free trial | \$100 credit, once per billing account | | Trial credit expiration | 90 days after issuance | | Minimum credit purchase | \$10 | | Default credit purchase | \$25 | | Purchased credit expiration | 365 days after purchase | | Automatic top-up | Off by default | | Default top-up threshold | \$10 | | Default top-up target | \$50 | | Automatic top-up monthly maximum | None | ## Limitations * Usage credits currently cover Agents model usage only. You can continue using other features for free. * Usage takes a few minutes to record, and model calls in progress are allowed to finish. A small amount of usage can therefore run past \$0. It is charged on your monthly usage invoice or covered by your next top-up. * Trial credits expire 90 days after issuance unless stated otherwise. Purchased credits expire 365 days after purchase. Both are non-refundable and non-transferable. # activity Source: https://docs.entire.com/cli-reference/activity Show your Entire activity overview from your hosted Entire account. Show your Entire activity overview from your hosted Entire account. ```bash theme={null} entire activity [flags] ``` This command loads your activity from the last month from [entire.com](https://entire.com), including: * Activity overview and aggregate stats * Repository breakdown * Recent sessions > [!NOTE] > > **Only published work appears here.** `entire activity` reads your account's activity from Entire's servers, across every repository you can see — it is not scoped to the current checkout. Work in a repository you have not [published to Entire](/guides/repositories/repository) and pushed is not included. | Flag | Description | | - | - | | `--commits` | Show recent commits instead of recent sessions | If you are not logged in, authenticate first: ```bash theme={null} entire login ``` When you run `entire activity` in an interactive terminal, it opens a richer terminal UI. In non-interactive contexts, such as piped output, or when accessibility mode is enabled with `ACCESSIBLE=1`, it falls back to a simpler static text view that works better with screen readers. ```bash theme={null} # Open the interactive activity view entire activity # Show recent commits instead of recent sessions entire activity --commits # Use simpler static output for screen readers ACCESSIBLE=1 entire activity ``` > [!NOTE] > > `entire activity` shows account-level activity from Entire, not just local repository state. # agent Source: https://docs.entire.com/cli-reference/agent Manage agent integrations in the current repository. Manage agent integrations in the current repository. ```bash theme={null} entire agent SUBCOMMAND ``` ## agent list List installed and available agents, including `antigravity` for [Antigravity CLI](/agents/antigravity). ```bash theme={null} entire agent list ``` ## agent add Install hooks for an agent. ```bash theme={null} entire agent add AGENT_NAME [flags] ``` Use this command to add an agent included with Entire or an `entire-agent-` executable that follows the [Agent Integration Protocol](/agents/agent-integration-protocol/overview). During initial repository setup, use [`entire enable --agent AGENT_NAME`](/cli-reference/enable) instead. | Flag | Description | | - | - | | `--agent-help-skill` | Install the Entire agent-help skill for the selected agent | | `--force` | Reinstall hooks even if already present | | `--search-skill` | Install the Entire search skill for the selected agent | See [Set Up an Agent](/agents/setup) for shared setup, hook locations, verification, and troubleshooting. ## agent remove Uninstall hooks for an agent. ```bash theme={null} entire agent remove AGENT_NAME ``` # agent-help Source: https://docs.entire.com/cli-reference/agent-help Show agent-facing usage that matches the installed Entire CLI. Show coding agents which Entire command to use and retrieve exact usage for the installed CLI. Unlike static command documentation, `agent-help` generates its output from the installed Entire binary. This helps agents avoid guessing commands or flags that may differ between CLI versions. ```bash theme={null} entire agent-help [COMMAND...] [flags] ``` With no command, `agent-help` prints a high-level map of available commands and when to use them: ```bash theme={null} entire agent-help ``` The output also identifies the repository detected from the Git remote. You do not need to provide the repository name when working in the current repository. ## Get Help for a Command Pass a command or nested command path to see its description, subcommands, and currently installed flags: ```bash theme={null} entire agent-help status entire agent-help checkpoint explain entire agent-help session resume ``` The command map only includes commands available in the current installation and repository. Commands that are deprecated, internal, or unavailable for the repository are omitted. ## Get Structured Output Use `--json` when an agent or script needs structured output: ```bash theme={null} entire agent-help --json entire agent-help checkpoint explain --json ``` The JSON response includes the command name, short and long descriptions, detected repository, subcommands, and flags when applicable. ## Flags | Flag | Description | | - | - | | `--json` | Emit structured JSON instead of text | | `--help`, `-h` | Show help for `agent-help` | > [!NOTE] > > `entire agent-help` describes the CLI installed on your machine. Use this command as the source of truth when its output differs from static documentation. # api Source: https://docs.entire.com/cli-reference/api Make an authenticated request to an Entire API and print the response. Make an authenticated HTTP request to an Entire API and print the JSON response. ```bash theme={null} entire api PATH [flags] ``` Entire selects the backend host and supplies the bearer token automatically. > [!WARNING] > > These internal endpoints may change without notice. Prefer dedicated CLI commands such as [`entire activity`](/cli-reference/activity), [`entire search`](/cli-reference/search), and [`entire repo`](/cli-reference/repo) when available. ## Choose a Backend | Value | Backend | | - | - | | `--to core` | The control plane. This is the default: orgs, repos, mirrors, clusters, and `/me`. | | `--to cell` | Your home `entire-api` cell: `/me/*` activity and repository aggregates. | Use `--jurisdiction SLUG` to reach a specific jurisdiction's cell instead of your home one. It implies `--to cell`. Find your home jurisdiction with [`entire auth status`](/cli-reference/auth#auth-status). ## Path Placeholders `PATH` is the full path on the chosen host, such as `/api/v1/clusters`. These placeholders are filled from the current repository's `origin` remote: | Placeholder | Value | | - | - | | `{owner}` | The GitHub owner | | `{repo}` | The GitHub repository name | | `{repo_id}` | The repository's Entire ULID, from its mirror. Cells key on this. | ## Flags | Flag | Description | | - | - | | `-F, --field KEY=VALUE` | Add a typed parameter. `true`, `false`, `null`, and numbers are converted. Repeatable. | | `-H, --header KEY:VALUE` | Add a request header. Repeatable. | | `-i, --include` | Print the response status line and headers too. | | `--input FILE` | File containing the request body. Use `-` for standard input. | | `-j, --jurisdiction SLUG` | Target a specific jurisdiction's cell, such as `us` or `eu`, instead of your home cell. Implies `--to cell`. | | `-X, --method METHOD` | HTTP method. Defaults to `GET`, or `POST` when a field or body is given. | | `-f, --raw-field KEY=VALUE` | Add a string parameter, with no type conversion. Repeatable. | | `--to BACKEND` | Which backend to call: `core` or `cell`. Defaults to `core`. | ## Examples ```bash theme={null} # Control plane entire api /api/v1/clusters # Your home cell entire api --to cell /api/v1/me/activity # A specific jurisdiction's cell entire api --jurisdiction eu /api/v1/me/activity # Fill the current repository's ULID into the path entire api --to cell "/api/v1/me/recap?repo={repo_id}" # POST with a string field entire api -X POST /api/v1/projects -f name=demo ``` ## Continue With > **[auth token](/cli-reference/auth#auth-token)** > > Get the bearer token itself, for use with `curl`. > **[repo](/cli-reference/repo)** > > Use the purpose-built commands where they exist. # auth Source: https://docs.entire.com/cli-reference/auth Manage authentication and saved login contexts. Manage authentication and saved login contexts. ```bash theme={null} entire auth SUBCOMMAND ``` ## Login Contexts A **context** is a saved login. Each one pairs a login server with an identity, and stores its tokens in your operating system's credential store. Contexts are recorded in `~/.config/entire/contexts.json`, or `$ENTIRE_CONFIG_DIR/contexts.json` when that variable is set. One context is active at a time. The active context supplies the identity for every authenticated operation: `git clone entire://…`, the control-plane commands ([`cluster`](/cli-reference/cluster), [`org`](/cli-reference/org), [`project`](/cli-reference/project), [`repo`](/cli-reference/repo)), and the data commands ([`activity`](/cli-reference/activity), [`search`](/cli-reference/search), [`dispatch`](/cli-reference/dispatch)). Entire names a new context after its login server's host. When you log in as a second identity on a host that already has a context, Entire names the new one `HANDLE@HOST` instead of replacing the first. To act as a different context for a single command, use the [`--context` global flag](/cli-reference/global-flags) instead of switching. ## auth login Authenticate with your Entire account. Equivalent to the top-level [`entire login`](/cli-reference/login). ```bash theme={null} entire auth login [flags] ``` See [`entire login`](/cli-reference/login) for the `--device` and `--server` flags. ## auth logout Sign out of your Entire account. Equivalent to the top-level [`entire logout`](/cli-reference/logout). ```bash theme={null} entire auth logout [flags] ``` It logs out of every saved context, not just the active one. See [`entire logout`](/cli-reference/logout) for the `--everywhere` flag. ## auth status Show authentication status for the active context. ```bash theme={null} entire auth status [flags] ``` The report is a verdict line and a few rows covering who you are signed in as, your home jurisdiction, where tokens are stored, and your sessions. The active context appears as its own row only when more than one login is saved. Timestamps are humanized, and `user` is shown as the provider-qualified handle you can paste into a [`grant`](/cli-reference/grant) command. Use it to find your home jurisdiction slug, which [`entire api`](/cli-reference/api) and [`entire dispatch`](/cli-reference/dispatch) accept as `--jurisdiction`. | Flag | Description | | - | - | | `--json` | Output as JSON. | | `--sessions` | Print the full session table, with the current CLI session marked. | ## auth contexts List saved login contexts and mark the active one. ```bash theme={null} entire auth contexts ``` The table shows each context's name, handle, and login server, with `(active)` in a trailing column on the one in use. This command is local only and makes no network requests. ```text theme={null} CONTEXT HANDLE LOGIN SERVER auth.entire.io octocat https://auth.entire.io (active) staging.entire.io octocat https://staging.entire.io ``` ## auth switch Switch the active login context. ```bash theme={null} entire auth switch [CONTEXT] ``` With no argument, Entire lists the saved contexts and asks which to switch to. Pass a name to switch without being asked. The switch takes effect on the next operation. It is persistent and machine-wide: it changes the identity for every shell, worktree, and background Git hook until you switch back. ```bash theme={null} entire auth switch staging.entire.io ``` ## auth token Print an Entire bearer token for use in scripts and `curl` requests. ```bash theme={null} entire auth token ``` This prints the same bearer the CLI's own API client uses: `ENTIRE_TOKEN` verbatim when that variable is set, otherwise the active context's login JWT, refreshed if it is near expiry. For using a token in CI or a cloud agent, see [CI and Automation](/cli-reference/login#ci-and-automation). One token covers everything. It works against the control-plane API — orgs, repos, clusters, `/me` — and against every `entire-api` cell. ```bash theme={null} curl -H "Authorization: Bearer $(entire auth token)" \ "https://us.console.entire.io/api/v1/clusters" curl -H "Authorization: Bearer $(entire auth token)" \ "https://aws-us-east-2.api.entire.io/api/v1/me/activity" ``` Only the token goes to standard output. Errors and the not-logged-in hint go to standard error, so command substitution stays clean. > [!WARNING] > > The output is a live credential. Treat it as a secret: do not log it, commit it, or paste it into a shared transcript. > [!NOTE] > > `--jurisdiction` is removed. It minted a separate jurisdictional token for a cell's API; the plain token is now accepted there directly, so drop the flag. Passing it fails with a migration hint. ## Continue With > **[Global Flags](/cli-reference/global-flags)** > > Act as another login for a single command with `--context`. > **[api](/cli-reference/api)** > > Make authenticated requests without handling tokens yourself. # blame Source: https://docs.entire.com/cli-reference/blame A git-blame-style command for viewing file history with checkpoint and session context. `entire blame` is a git-blame-style command for viewing file history with checkpoint and session context. ```bash theme={null} entire blame FILE[:LINE[-LINE]] [flags] ``` Traditional `git blame` tells you which commit and Git author last touched each line. But after agent-assisted work, the Git author is often not the whole story. `entire blame` starts from the same line history, then tells you the intent behind how the code was created: the prompt that asked for it, the session it came from, and the checkpoint that saved it. [Entire blame demo](https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/ab2d696d319f2f9d1643c9e57f8132a2/iframe?muted=true\&loop=true\&autoplay=true\&poster=https%3A%2F%2Fcustomer-0x5hsk8lh27fm00g.cloudflarestream.com%2Fab2d696d319f2f9d1643c9e57f8132a2%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600) Use `entire blame` when you need to review agent-assisted changes, audit a suspicious line, or find the checkpoint behind a specific change. The command works in Entire-enabled repositories and supports JSON output for scripts and tooling. ## Try it Run `entire blame` from an Entire-enabled repository, then pass the file you want to inspect. ```bash theme={null} entire blame path/to/file.ts entire blame path/to/file.ts --line 12-20 entire blame path/to/file.ts --long entire blame path/to/file.ts --json ``` `FILE:12` and `FILE:12-20` are equivalent to passing `--line`. ## Attribution Tags Each line shows the attribution status of the commit that introduced it. Tags are commit-level signals: * `AI`: the commit was attributed to an AI agent session * `MX`: the commit mixed AI-attributed and human-attributed work * `HU`: the commit was made without AI-attributed checkpoint data * `??`: the line is uncommitted When available, the output also links lines to their Entire checkpoint metadata. A line never changes tag between `entire blame` and [`entire why`](/cli-reference/why). See [What do `entire blame` and `entire why` actually tell me?](/faq#what-do-entire-blame-and-entire-why-actually-tell-me) for what these tags do and do not promise. ## Flags | Flag | Description | | - | - | | `--line LINE_OR_RANGE` | Only show a line or range, for example `12` or `12-20` | | `--long` | Show the full attribution table with agent, model, author, and session columns | | `--json` | Output attribution as JSON | ## Continue With > **[Investigate Why Code Exists](/learn/investigate-why-code-exists)** > > Trace a surprising line from attribution to checkpoint context. > **[why](/cli-reference/why)** > > Explain the context behind a file or line. > **[Introducing entire blame](https://entire.com/blog/introducing-entire-blame)** > > Read the launch post on the Entire blog. # checkpoint Source: https://docs.entire.com/cli-reference/checkpoint List, explain, measure, search, and delete checkpoints. Work with checkpoints captured by Entire. ```bash theme={null} entire checkpoint SUBCOMMAND ``` `entire checkpoint` is also available as `entire cp` and `entire checkpoints`. ## checkpoint list List checkpoints on the current branch. ```bash theme={null} entire checkpoint list [flags] ``` | Flag | Description | | - | - | | `--json` | Output as JSON instead of the human view | | `--no-pager` | Disable pager output | | `--pending` | List the live session's shadow-branch rewind points, plus logs-only resume points recovered from commits whose logs are already condensed, instead of condensed checkpoints | | `--session ID` | Filter checkpoints by session ID (or prefix). Not valid with `--pending` | ## checkpoint explain Show human-readable context for checkpoints, sessions, and commits. Add `--generate` for an AI-written summary. ```bash theme={null} entire checkpoint explain [CHECKPOINT_ID | COMMIT_SHA] [flags] ``` | Flag | Description | | - | - | | `-c, --checkpoint ID` | Explain a specific checkpoint (ID or prefix) | | `--commit SHA` | Explain a specific commit (SHA or ref, "commit-ish") | | `--force` | Regenerate summary even if one already exists (requires `--generate`) | | `--full` | Show full parsed transcript (all prompts/responses) | | `--generate` | Generate an AI summary for the checkpoint | | `--insecure-http-auth` | Allow plain HTTP auth for `--repo`. Local development only. | | `--json` | Output metadata as JSON. See [Machine-Readable Output](#machine-readable-output). | | `--limit N` | Cap the list view at N checkpoints. Defaults to `100`. Only meaningful with `--json`. | | `--no-pager` | Disable pager output | | `--raw-transcript` | Show raw transcript file (JSONL format) | | `--repo REPO` | A forge-qualified reference: `gh/OWNER/REPO` or `et/PROJECT/REPO`. See [Explain a Checkpoint in Another Repository](#explain-a-checkpoint-in-another-repository). | | `--search-all` | Search all commits (no branch/depth limit, may be slow) | | `--session ID` | Filter checkpoints by session ID (or prefix) | | `--session-index N` | Pick a session within a multi-session checkpoint, 0-based. Defaults to the latest. Only meaningful with `--transcript` or `--raw-transcript`. | | `-s, --short` | Show summary only (omit prompts and files) | | `--task ID` | With `--transcript`, stream a subagent's stored transcript instead, selected by `tool_use_id` or `agent_id` as listed under `tasks` in `--json`. | | `--summary-timeout-seconds N` | Hard deadline in seconds for `--generate`. Overrides the `summary_timeout_seconds` setting. `0` uses the setting; if that is also unset, no automatic deadline applies. | | `--transcript` | Stream stored checkpoint transcript bytes (JSONL) to stdout: a session's, or a subagent's with `--task` | > [!NOTE] > > The `--generate` flag requires the configured provider CLI, such as Claude CLI, to be installed and authenticated. ### Machine-Readable Output `--json` emits metadata only. With no target it lists checkpoints; with a target it emits a single checkpoint envelope, including its subagent task records under `tasks` and the full session token breakdown (`subagent_tokens`, `subagent_tokens_complete`, `api_call_count`). Transcript bytes are never embedded in that envelope. To get the transcript itself, use `--transcript`, which streams the stored checkpoint transcript bytes to standard output: ```bash theme={null} entire checkpoint explain 01KVBJCW --json entire checkpoint explain 01KVBJCW --transcript > session.jsonl entire checkpoint explain 01KVBJCW --transcript --session-index 0 > first-session.jsonl entire checkpoint explain 01KVBJCW --transcript --task TOOL_USE_ID > subagent.jsonl ``` ### Explain a Checkpoint in Another Repository `--repo` reads a checkpoint owned by a different repository through that repository's Entire API. It takes a forge-qualified reference — `gh/OWNER/REPO` or `et/PROJECT/REPO`, or a full `entire://` URL — and refuses a bare `owner/repo`. This is the drill-down for a cross-repo [`entire search`](/cli-reference/search) hit. Nothing is written to the current repository. ```bash theme={null} entire checkpoint explain CHECKPOINT_ID --repo gh/owner/name ``` This needs the full checkpoint ID, passed positionally or with `--checkpoint`, and a checkpoint that has been pushed. ## checkpoint tokens Show token usage and optimization recommendations for a checkpoint. ```bash theme={null} entire checkpoint tokens CHECKPOINT_ID [flags] ``` | Flag | Description | | - | - | | `--agent-brief` | Output compact next-step guidance for agents | | `--compare ID` | Compare against a baseline checkpoint ID | | `--json` | Output as JSON | `--json` and `--agent-brief` are mutually exclusive. The report resolves its target through the same path as `checkpoint explain`: an unambiguous checkpoint ID prefix, or a commit-ish carrying an `Entire-Checkpoint` trailer. Metadata missing locally is fetched from the checkpoint remote. ```bash theme={null} entire checkpoint tokens 01KVBJCW entire checkpoint tokens 01KVBJCW --compare 01KVBK7Q entire checkpoint tokens 01KVBJCW --json ``` ## checkpoint delete Delete one checkpoint from this repository and from every checkpoint remote that holds it. ```bash theme={null} entire checkpoint delete CHECKPOINT_ID [flags] ``` The full checkpoint ID is required; prefixes are not accepted. Deleting from a remote cannot be undone. Without `--force`, the command asks for confirmation and refuses when it cannot prompt. | Flag | Description | | - | - | | `--dry-run` | Print what would be deleted without changing anything | | `-f`, `--force` | Delete without asking for confirmation | | `--json` | Output as JSON | | `--local-only` | Delete only the local copy; leave every remote untouched | | `--remote REMOTE` | Limit remote deletion to this remote; the local copy is still deleted. Repeatable. `checkpoint_remote` names the dedicated checkpoint remote | > [!WARNING] > > Deleting a checkpoint is not a full purge. Other checkpoints from the same session are listed but not deleted, and each one carries the session's full transcript, so the session stays visible on entire.com while any of them remain. On the legacy `entire/checkpoints/v1` branch, the checkpoint is removed from the branch tip only, and the branch's history still contains it. On the `git-branch` backend, a local removal reaches the sync remote on the next `git push`, so `--local-only` (or a `--remote` selection that leaves that remote out) is refused while it holds a copy or cannot be reached. With `push_sessions` disabled the removal is not pushed, but re-enabling it later pushes it. ```bash theme={null} entire checkpoint delete 01KVBJCWQ1A2B3C4D5E6F7G8H9 --dry-run entire checkpoint delete 01KVBJCWQ1A2B3C4D5E6F7G8H9 entire checkpoint delete 01KVBJCWQ1A2B3C4D5E6F7G8H9 --remote origin --force ``` ## checkpoint search Search checkpoints using semantic and keyword matching. ```bash theme={null} entire checkpoint search [QUERY] [flags] ``` `entire checkpoint search` is an alias for [`entire search`](/cli-reference/search). See that page for the [flags](/cli-reference/search#flags), inline filters, code search, and the interactive result view. # clean Source: https://docs.entire.com/cli-reference/clean Clean up Entire session data. Clean up Entire session data. ```bash theme={null} entire clean [flags] ``` | Flag | Description | | - | - | | `-a, --all` | Clean all Entire session data across the repository | | `-d, --dry-run` | Show what would be cleaned without actually deleting | | `-f, --force` | Skip confirmation and override the active-session guard | | `--session ID` | Clean a specific session by ID | By default, `entire clean` removes session data for the current `HEAD` commit: * Session state files for sessions based on the current commit * The shadow branch for the current commit and worktree Use `--session ID` to clean a single session. This removes the session state and deletes its shadow branch if no other session still needs it. File changes remain in your working directory. Use `--all` to clean Entire session data across the repository: * All session state files in `.git/entire-sessions/` * All shadow branches * Temporary files in `.entire/tmp/` Committed checkpoint data is preserved: the refs under `refs/entire/checkpoints/`, or the `entire/checkpoints/v1` branch in repositories that use the legacy branch backend. ```bash theme={null} # Preview cleanup for the current HEAD entire clean --dry-run # Clean one session entire clean --session 2026-02-02-test123 --force # Clean all session data in the repository entire clean --all --force ``` > [!NOTE] > > `entire reset` has been removed. Use `entire clean` instead, or `entire clean --all` for repository-wide cleanup. # cluster Source: https://docs.entire.com/cli-reference/cluster Show the Entire clusters you can place projects and repositories on. Show the Entire clusters you can place projects and repos on. ```bash theme={null} entire cluster SUBCOMMAND ``` A cluster is one regional EntireDB deployment. Clusters are where [repositories](/cli-reference/repo) are provisioned and where [mirror placements](/guides/repositories/mirrors) live, and their public hosts are what `--cluster` accepts elsewhere in the CLI. ## cluster list List the clusters Entire has available. ```bash theme={null} entire cluster list [flags] ``` The table shows three columns, each a value another command takes: `REGION` is the jurisdiction slug [`entire org create --region`](/cli-reference/org) and [`entire project create --region`](/cli-reference/project) name, `CLUSTER` is the cluster's placement slug, and `HOST` is what every `--cluster` flag takes, including the [`entire repo mirror list --cluster`](/cli-reference/repo#entire-repo-mirror-list) filter. A `DEFAULT` column appears only when some cluster is not its region's default. It marks the default within each region, not one global default. Pass the `HOST` value — such as `aws-us-east-2.entire.io`, not the region or slug — to [`entire repo mirror add --cluster`](/cli-reference/repo#entire-repo-mirror-add), [`entire repo mirror list --cluster`](/cli-reference/repo#entire-repo-mirror-list), [`entire repo clone --cluster`](/cli-reference/repo#entire-repo-clone), and [`entire repo remote add --cluster`](/cli-reference/repo#entire-repo-remote-add). [`entire auth status`](/cli-reference/auth#auth-status) shows your home jurisdiction. ```bash theme={null} entire cluster list entire cluster list --json ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | ## Continue With > **[repo](/cli-reference/repo)** > > Create repositories and mirror placements on a cluster. > **[Mirrors](/guides/repositories/mirrors)** > > Understand how regional placements work. # completion Source: https://docs.entire.com/cli-reference/completion Generate a shell completion script for the Entire CLI. Generate the autocompletion script for `entire` for the specified shell. ```bash theme={null} entire completion SHELL ``` | Shell | Command | | - | - | | Bash | `entire completion bash` | | Zsh | `entire completion zsh` | | Fish | `entire completion fish` | | PowerShell | `entire completion powershell` | Each subcommand prints a script to stdout. Run `entire completion SHELL --help` for the shell-specific instructions on where to load it. For Bash and Zsh, the quickest option is to source it from your shell profile: ```bash theme={null} source <(entire completion zsh) ``` See [Shell Completion](/installation#shell-completion) in the installation guide for profile snippets. ## Continue With > **[Installation](/installation)** > > Install and update the Entire CLI. > **[Global Flags](/cli-reference/global-flags)** > > Flags every command accepts. # configure Source: https://docs.entire.com/cli-reference/configure Update non-agent Entire settings in the current repository, such as telemetry, Git hook installation mode, strategy options, and the summary provider. Update non-agent Entire settings in the current repository: telemetry, Git hook installation mode, strategy options, and the summary provider. Agent hook installation is handled by [`entire agent`](/cli-reference/agent). Running `entire configure` with no flags prints its help. ```bash theme={null} entire configure [flags] ``` | Flag | Description | | - | - | | `--absolute-git-hook-path` | Embed full binary path in Git hooks. Required for GUI Git clients that don't source shell profiles. See [GUI Git Clients](/guides/configuration/git-hooks#gui-git-clients). | | `--checkpoint-backend BACKEND` | Set checkpoint storage to `refs` (one Git ref per checkpoint) or `branch` (one shared branch). | | `--checkpoint-remote PROVIDER:OWNER/REPO` | Push checkpoint data to a separate repository. `PROVIDER` is `github` or `gitlab`, as in `github:org/checkpoints-private`. See [Checkpoint Remote](/guides/checkpoints/store-checkpoints-in-another-repo). | | `-f, --force` | Force reinstall the Entire Git hook | | `--local` | Write settings to `.entire/settings.local.json` instead of `.entire/settings.json` | | `--project` | Write settings to `.entire/settings.json` even if it already exists | | `--skip-push-sessions` | Disable automatic pushing of session logs on Git push | | `--summarize-model MODEL` | Set the model hint used by `checkpoint explain --generate` | | `--summarize-provider PROVIDER` | Set the provider used by `checkpoint explain --generate`. Requires an installed agent that supports text generation. | | `--summarize-timeout-seconds N` | Set the hard deadline in seconds for `checkpoint explain --generate`. `0` clears the setting, leaving summary generation unbounded. | | `--telemetry` | Enable anonymous usage analytics (default: true) | Use `entire agent remove NAME` to uninstall hooks for a specific agent. # disable Source: https://docs.entire.com/cli-reference/disable Disable Entire in a repository. Hooks stay installed but exit silently, so session capture stops while existing session data is preserved. Disable Entire in a repository. Hooks stay installed but exit silently, so session capture stops while existing session data is preserved. Commands show a disabled message. ```bash theme={null} entire disable [flags] ``` | Flag | Description | | - | - | | `--force` | Skip confirmation prompt (use with `--uninstall`) | | `--local` | Update `.entire/settings.local.json`. This is the default. | | `--project` | Update `.entire/settings.json` instead of `.entire/settings.local.json` | | `--uninstall` | Completely remove Entire from this repository: `.entire/`, Git hooks, agent hooks, session state, and shadow branches | > [!NOTE] > > Disabling Entire does not delete your session history. You can re-enable at any time with `entire enable`. Use `--uninstall` to completely remove Entire from the repository. # dispatch Source: https://docs.entire.com/cli-reference/dispatch Generate a dispatch summarizing recent agent work. Generate a dispatch summarizing recent agent work. ```bash theme={null} entire dispatch [flags] ``` `entire dispatch` has two modes: * **Cloud mode** (default) generates a dispatch from Entire server data * **Local mode** (`--local`) generates a dispatch from local repository data using your locally installed agent CLI Cloud mode carries the requirement below, and covers repositories placed in exactly one jurisdiction — the cell for that jurisdiction generates the dispatch. Local mode reads the repository on disk instead, so it works without a published repository. > [!NOTE] > > **Requires a published repository.** Entire answers this from its own servers rather than from your local clone, so the repository must be published somewhere Entire can reach and its checkpoints pushed. > > Publish by [creating a repository on Entire](/guides/repositories/repository) or by [mirroring a GitHub repository](/guides/repositories/mirrors), then `git push`. `entire enable` does not create or push to a remote for you. > > Your work becomes available shortly after it reaches Entire, so give a recent push a couple of minutes before treating a missing result as a problem. If you run `entire dispatch` with no flags in an interactive terminal, Entire launches a guided wizard. In non-interactive contexts, or whenever you provide flags, it prints markdown output directly. | Flag | Description | | - | - | | `--local` | Generate via the locally installed agent CLI instead of the Entire server | | `--since TIME` | Start of the time window. Accepts Go durations, relative times, or ISO dates. Defaults to `7d`. | | `--until TIME` | End of the time window. Defaults to now. | | `--all-branches` | Include every existing local branch. Only valid with `--local`. | | `--repos REPO` | Limit cloud dispatch to up to 5 repositories, comma-separated. Each is forge-qualified: `gh/OWNER/REPO` or `et/PROJECT/REPO`. | | `--voice PRESET_OR_TEXT` | Customize the dispatch tone with a preset such as `neutral` or `marvin`, or provide your own text. | | `--agent NAME` | Local text-generation agent to use. Only valid with `--local`. | | `-j, --jurisdiction SLUG` | Jurisdiction whose cell generates the cloud dispatch, such as `us` or `eu`. Defaults to your home jurisdiction. | Use cloud mode when you want a dispatch from Entire-tracked repo data: ```bash theme={null} # Default dispatch for recent work in the current repo entire dispatch # Limit cloud dispatch to specific repos entire dispatch --repos gh/entireio/cli,et/myproject/service ``` Use local mode when you want a dispatch from local repository history: ```bash theme={null} # Local dispatch from the current branch entire dispatch --local # Local dispatch across all local branches entire dispatch --local --all-branches ``` You can also customize the dispatch voice: ```bash theme={null} entire dispatch --voice neutral ``` > [!NOTE] > > `--repos` cannot be combined with `--local`, and `--all-branches` only applies to `--local`. > [!NOTE] > > Cloud dispatch supports up to 5 repositories per request, and each must be forge-qualified as `gh/OWNER/REPO` or `et/PROJECT/REPO`. A bare `owner/repo` is refused. ## Jurisdictions A cloud dispatch covers repositories placed in exactly one jurisdiction, and is generated by that jurisdiction's cell. Without `--jurisdiction`, Entire uses your home jurisdiction, which [`entire auth status`](/cli-reference/auth#auth-status) reports. A repository mirrored only elsewhere is reported as not found in your home jurisdiction. Pass `--jurisdiction SLUG` to target the jurisdiction the repository is actually placed in: ```bash theme={null} entire dispatch --repos gh/entirehq/ferrata --jurisdiction us ``` # doctor Source: https://docs.entire.com/cli-reference/doctor Diagnose session, log, and hook problems in a repository, and offer to fix them. Diagnose problems in the current repository and offer to fix them. ```bash theme={null} entire doctor [flags] ``` | Flag | Description | | - | - | | `-f, --force` | Fix all issues without prompting (condense if possible, otherwise discard) | ## What Doctor Checks | Check | What it reports | | - | - | | Disconnected metadata branches | The local and remote `entire/checkpoints/v1` branches share no common ancestor. Doctor fixes this by cherry-picking local checkpoints onto the remote tip. | | Operational logs | Entire cannot write to `.entire/logs`, so diagnostics may be missing. | | Codex hook trust | Installed Codex hooks lack a `trusted_hash` entry in your Codex config. Review and approve them with `/hooks` in Codex. | | Hook config drift | Installed agent hooks differ from the current CLI configuration. Run `entire enable --force` to reinstall them. | | Stuck sessions | See [Stuck Sessions](#stuck-sessions) below. | ## Stuck Sessions A session is considered stuck if: * It is in ACTIVE phase with no interaction for over 1 hour * It is in ENDED phase with uncondensed checkpoint data on a shadow branch For each stuck session, you can choose to: * **Condense**: Save session data to permanent [checkpoint storage](/guides/checkpoints/checkpoint-storage) * **Discard**: Remove the session state and shadow branch data * **Skip**: Leave the session as-is Without a terminal to prompt on, such as an agent or CI, `entire doctor` reports each issue and points at `--force` instead of prompting. ## doctor migrate-checkpoints Convert the checkpoints on the `entire/checkpoints/v1` branch into per-checkpoint refs under `refs/entire/checkpoints//`, the layout the ref-based backend uses. ```bash theme={null} entire doctor migrate-checkpoints [flags] ``` | Flag | Description | | - | - | | `--dry-run` | Report what would be migrated without writing refs | | `--remote NAME` | Remote to push migrated refs to. Defaults to the checkpoint sync remote | Each checkpoint keeps its 12-character hex ID as the ref name, and its current tree is wrapped in a fresh commit. The command does not remap the existing branch commits and does not delete the branch. It skips checkpoints it has already converted, so re-running it after more branch activity is safe. Run it while the branch backend is still primary. Once `checkpoints.primary.type` is `git-refs`, the command reports that there is nothing to migrate and exits, because the refs are authoritative at that point. New refs are queued for push. Run interactively, the command asks whether to push them now. Run without a terminal, it leaves them queued, and they flush on the next `git push` once the ref-based backend is primary. > [!NOTE] > > Migration is optional. See [Both Backends Stay Readable](/guides/checkpoints/checkpoint-storage#both-backends-stay-readable) for how readers resolve branch-backed checkpoints after a switch. ## doctor logs Show recent operational logs. ```bash theme={null} entire doctor logs [flags] ``` | Flag | Description | | - | - | | `-f, --follow` | Stream new log lines as they are written | | `--tail N` | Show the last N lines. Use `0` for all. Defaults to `100`. | ## doctor bundle Produce a diagnostic bundle for bug reports. ```bash theme={null} entire doctor bundle [flags] ``` | Flag | Description | | - | - | | `-o, --out PATH` | Path to write the bundle archive. Defaults to the OS temp directory. | | `--raw` | Skip secret redaction. Use only when support has asked for an unredacted bundle. | ## doctor trace Show hook performance traces for debugging slow Git operations. ```bash theme={null} entire doctor trace [flags] ``` | Flag | Description | | - | - | | `--hook TYPE` | Filter by hook type, such as `post-commit`, `prepare-commit-msg`, or `pre-push` | | `--json` | Output as JSON | | `--last N` | Show the last N hook invocations. Defaults to `1`. | | `--slow` | Only include traces flagged slow, meaning those logged at WARN | | `--summary` | Aggregate across traces instead of showing each one, reporting which step dominates per hook. Uses `--last 200` unless you set `--last`. | ```bash theme={null} # The most recent hook trace entire doctor trace # The last five post-commit traces entire doctor trace --last 5 --hook post-commit # Which step dominates, across the slow traces only entire doctor trace --summary --slow ``` Hooks that take 1.5 seconds or longer are traced by default, at WARN level, so a slow hook records its own breakdown with no configuration. Set `ENTIRE_PERF_SLOW_MS=0` to turn that off. A `log_level` above WARN also hides them. > [!NOTE] > > To trace every hook, including fast ones, raise verbosity: set `ENTIRE_LOG_LEVEL=DEBUG` in your shell profile, or add `"log_level": "DEBUG"` to `.entire/settings.json`. # enable Source: https://docs.entire.com/cli-reference/enable Initialize Entire in a Git repository. This installs the necessary Git hooks to capture AI coding sessions. Initialize Entire in a Git repository. This installs the necessary Git hooks to capture AI coding sessions. ```bash theme={null} entire enable [flags] ``` If Entire is not yet configured, this runs the full configuration flow. If Entire is already configured but disabled, this re-enables it. In a directory that is not a Git repository, see [Bootstrap a New Repository](#bootstrap-a-new-repository). ## Flags | Flag | Description | | - | - | | `--absolute-git-hook-path` | Embed full binary path in Git hooks. Required for GUI Git clients that don't source shell profiles. See [GUI Git Clients](/guides/configuration/git-hooks#gui-git-clients). | | `--agent NAME` | Agent to set up hooks for: [`antigravity`](/agents/antigravity), `claude-code`, `codex`, `opencode`, `cursor`, `copilot-cli`, `factoryai-droid`, `pi`, or an `entire-agent-` executable that follows the [Agent Integration Protocol](/agents/agent-integration-protocol/overview). Runs without prompts. | | `--agent-help-skill` | Install the Entire agent-help Skill, which points agents at [`entire agent-help`](/cli-reference/agent-help), for the selected agents. | | `--checkpoint-backend BACKEND` | Set checkpoint storage to `refs` (one Git ref per checkpoint) or `branch` (one shared branch). A first-time setup uses `refs` when you omit the flag. | | `--checkpoint-push-remote NAME` | Git remote that receives checkpoint uploads. Saved to `.entire/settings.local.json`, even with `--project`. Mutually exclusive with `--checkpoint-remote`. Without it, Entire asks which remote to use only during first-time interactive setup, without `--agent`, and only when more than one remote is eligible; `--yes`, `--skip-push-sessions`, and `--checkpoint-remote` skip the question and leave automatic election in place. | | `--checkpoint-remote PROVIDER:OWNER/REPO` | Push checkpoint data to a separate repository. `PROVIDER` is `github` or `gitlab`, as in `github:org/checkpoints-private`. See [Checkpoint Remote](/guides/checkpoints/store-checkpoints-in-another-repo). | | `-f, --force` | Force reinstall hooks (removes existing Entire hooks first) | | `--import-history` | During first-time setup, import the selected agents' existing session history from the last 30 days without prompting. See [`entire import`](/cli-reference/import). | | `--local` | Write settings to `.entire/settings.local.json` instead of `.entire/settings.json`. | | `--project` | Write settings to `.entire/settings.json` even if it already exists | | `--search-skill` | Install the Entire search Skill for the selected agents. See [`entire search`](/cli-reference/search). | | `--skip-push-sessions` | Disable automatic pushing of session logs on Git push | | `--telemetry` | Enable anonymous usage analytics (default: true) | | `-y, --yes` | Accept defaults without prompting. Useful for automation, CI, and bootstrap flows. | Use `--yes` for non-interactive setup flows: ```bash theme={null} # Non-interactive setup for a specific agent entire enable --yes --agent claude-code # Non-interactive setup using default choices entire enable --yes ``` To add another agent after initial setup, run [`entire agent add AGENT_NAME`](/cli-reference/agent#agent-add). `--yes` is not just a confirmation bypass. It runs `entire enable` non-interactively with default choices. On a fresh repository, it enables the default setup without prompts. On an already configured repository, it follows the setup-management path. Outside a Git repository, it also accepts the bootstrap defaults to initialize Git and create the initial commit. Important behavior: * If you also pass `--agent NAME`, that explicit agent selection takes precedence over the default multi-agent behavior. * If you pass `--telemetry=false`, or set `ENTIRE_TELEMETRY_OPTOUT`, that explicit telemetry opt-out still overrides the `--yes` default. * `--yes` does not import existing agent history. Add `--import-history` when you want the last 30 days of transcripts imported too. > [!NOTE] > > The `--local` and `--project` flags control which Entire settings file is modified. Entire always modifies the agent's **project** settings (e.g., `.agents/hooks.json`, `.claude/settings.json`, `.opencode/plugins/entire.ts`, `.factory/settings.json`, or `.pi/extensions/entire/index.ts`). ## Bootstrap a New Repository When run outside a Git repository, `entire enable` offers to initialize one and make the initial commit. It never creates or pushes to a remote, so publish the repository yourself when you are ready. Until you do, the commands that read from Entire's servers — [`search`](/cli-reference/search), [`activity`](/cli-reference/activity), [`experts`](/cli-reference/experts), and cloud [`dispatch`](/cli-reference/dispatch) — have nothing to return. Publish by [creating an Entire repository](/guides/repositories/repository) or [mirroring a GitHub repository](/guides/repositories/mirrors). Use these flags for non-interactive setup: | Flag | Description | | - | - | | `--init-repo` | Initialize a Git repository non-interactively when the directory is not one. | | `--no-init-repo` | Exit instead of prompting to initialize a repository. | | `--initial-commit-message MESSAGE` | Commit message for the initial commit. | | `--skip-initial-commit` | Don't create the initial commit. | ```bash theme={null} # Initialize a repository and commit, without prompts entire enable --init-repo --agent claude-code # Initialize with your own first commit message entire enable --init-repo --initial-commit-message "Start project" --agent claude-code # Fail rather than prompt when this isn't a repository entire enable --no-init-repo ``` # experts Source: https://docs.entire.com/cli-reference/experts Rank agents, Skills, and tools by their contributions to a file, directory, or topic. Rank agents, Skills, and tools by their contributions to a file, directory, or topic. ```bash theme={null} entire experts [SCOPE_OR_QUERY] [flags] ``` `entire experts` is experimental and appears under [labs](/cli-reference/labs) while the workflow is still being refined. > [!NOTE] > > **Requires a published repository.** Entire answers this from its own servers rather than from your local clone, so the repository must be published somewhere Entire can reach and its checkpoints pushed. > > Publish by [creating a repository on Entire](/guides/repositories/repository) or by [mirroring a GitHub repository](/guides/repositories/mirrors), then `git push`. `entire enable` does not create or push to a remote for you. > > Your work becomes available shortly after it reaches Entire, so give a recent push a couple of minutes before treating a missing result as a problem. ## Inputs The argument is either a single scope, meaning a file or directory path, or a natural-language query. One of the two is required unless you pass `--staged`, which uses your staged file paths as the scopes instead. ## Flags | Flag | Description | | - | - | | `--branch NAME` | Branch to inspect. | | `--json` | Print JSON. | | `--limit N` | Maximum profiles to return, from 1 to 20. Values above 20 are clamped. Defaults to `8`. | | `--repo OWNER/REPO` | Repository to inspect. | | `--staged` | Use staged file paths as the scopes. | | `--tui` | Browse provenance in an interactive viewer. Requires a terminal. | ## Examples ```bash theme={null} # Provenance for a directory entire experts src/payments --json # Provenance for a natural-language query entire experts "who owns token refresh" # Provenance for what you are about to commit entire experts --staged ``` > [!NOTE] > > The repository must be [mirrored](/guides/repositories/mirrors). ## Continue With > **[blame](/cli-reference/blame)** > > See per-line attribution for a single file. > **[why](/cli-reference/why)** > > Explain the context behind a file or line. # Global Flags Source: https://docs.entire.com/cli-reference/global-flags Shared flags and environment variables, plus the root-only version flag. These flags are available on the root command and on every subcommand: | Flag | Description | | - | - | | `--context NAME` | Act as this saved login for this command only, instead of the active context. It propagates to the Git and agent processes the command spawns. Run [`entire auth contexts`](/cli-reference/auth#auth-contexts) to list the names. | | `--help`, `-h` | Show help for `entire` or any subcommand | ```bash theme={null} # Run one command as another saved login entire --context staging activity ``` `--context` does not change the active context. To switch it persistently, use [`entire auth switch`](/cli-reference/auth#auth-switch). Entire passes the selection to child processes through `ENTIRE_CONTEXT`, so a spawned `git clone` or agent uses the same login. An unknown context name is rejected before any child runs. `--context` does not reach plugin commands such as [`entire investigate`](/cli-reference/investigate) or [`entire graph`](/cli-reference/graph). Set `ENTIRE_CONTEXT` in the environment for those. ## Version Flag `--version` (`-v`) is available only on the root command. Use `entire --version` or [`entire version`](/cli-reference/version) to show build information. ## Environment Variables | Variable | Description | | - | - | | `ACCESSIBLE` | Set to any value to enable accessibility mode. Entire uses simpler text prompts instead of interactive terminal UI, which works better with screen readers. | | `ENTIRE_CONTEXT` | Act as this saved login for a shell or a single Git operation. The environment-variable equivalent of `--context`. | ```bash theme={null} # Use a saved login for one Git operation ENTIRE_CONTEXT=staging git push # Use simpler static output for screen readers ACCESSIBLE=1 entire activity ``` See [Logging and Diagnostics](/guides/configuration/logging-and-diagnostics) for the variables that control log level and diagnostics. # grant Source: https://docs.entire.com/cli-reference/grant Manage Entire access grants and organization membership. Manage Entire access grants and organization membership. ```bash theme={null} entire org grant COMMAND entire project grant COMMAND entire repo grant COMMAND ``` Grants are managed at three levels, each under the command for the thing it governs: membership in an [organization](/cli-reference/org), access to a [project](/cli-reference/project), and access to a [repository](/cli-reference/repo). A **grantee** is addressed as a provider-qualified handle, such as `github:alice`, and nothing else. An account ULID is refused, including by `remove`. Orgs and projects are addressed by name or ULID, and repositories by their `/et/PROJECT/REPO` path. Omit the grantee on a terminal and most of these offer an interactive multi-select of candidates, with a role per grantee for `add`. `entire org grant add` is the exception: it always requires the grantee. `add` and `list` accept `--json` to print raw JSON instead of a table. `remove` does not. > [!NOTE] > > Access to a [GitHub mirror](/guides/repositories/mirrors) follows GitHub collaborator permissions and syncs hourly, rather than being managed with these commands. `entire repo grant list` reads a mirror's access with a `/gh/` reference, but `add` and `remove` take `/et/` references only. See [Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions). ## entire org grant Manage organization membership. ### `entire org grant add` Grant a user org access. ```bash theme={null} entire org grant add ORG GRANTEE [flags] ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | | `--role ROLE` | Org role: `owner`, `admin`, or `member`. Defaults to `member`. | ```bash theme={null} entire org grant add acme github:alice --role admin ``` ### `entire org grant list` List who has org access. ```bash theme={null} entire org grant list ORG [flags] ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | ### `entire org grant remove` Revoke a user's org access. ```bash theme={null} entire org grant remove ORG [GRANTEE] ``` ```bash theme={null} entire org grant remove acme github:alice ``` ## entire project grant Manage project access. ### `entire project grant add` Grant a user project access. ```bash theme={null} entire project grant add PROJECT [GRANTEE] --role ROLE [flags] ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | | `--role ROLE` | Project role: `reader`, `writer`, or `admin`. Required, though Entire asks for it if you omit it on a terminal. | ```bash theme={null} entire project grant add widgets github:alice --role writer ``` ### `entire project grant list` List who has project access. ```bash theme={null} entire project grant list PROJECT [flags] ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | ### `entire project grant remove` Revoke a grantee's project access. ```bash theme={null} entire project grant remove PROJECT [GRANTEE] ``` ```bash theme={null} entire project grant remove widgets github:alice ``` ## entire repo grant Manage repository access. The repository is addressed by its `/et/PROJECT/REPO` path. ### `entire repo grant add` Grant a user repo access. Takes an `/et/PROJECT/REPO` reference; a mirror's access is managed on GitHub. ```bash theme={null} entire repo grant add REPO [GRANTEE] --role ROLE [flags] ``` Omit `GRANTEE` on a terminal to choose from the members of the owning org who do not have repo access yet, and set a role for each. | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | | `--role ROLE` | Repo role: `reader`, `writer`, or `admin`. Required, though Entire asks for it if you omit it on a terminal. | ```bash theme={null} entire repo grant add /et/acme/web github:alice --role writer ``` ### `entire repo grant list` List who can reach a repository. This one answers for both forges. ```bash theme={null} entire repo grant list REPO [flags] ``` An `/et/PROJECT/REPO` reference lists the repository's grants: each grantee, their `reader`, `writer`, or `admin` role, and whether the grant is held on the repository itself or inherited. A `/gh/OWNER/REPO` reference lists who can pull the mirror. That access follows the upstream GitHub repository and is read-only here. The check runs live against your own GitHub identity, so you must be a current admin of the upstream repository or the owner of a personal one. Run it as yourself rather than with a service-account token. ```bash theme={null} entire repo grant list /et/acme/web entire repo grant list /gh/acme/widget ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. Every row carries `granteeId`, `role`, and `source`, plus `granteeName` when a name resolved, so one script reads either forge. A mirror's rows carry no `granteeType`, because that endpoint reports no grantee kind. | ### `entire repo grant remove` Revoke a grantee's repo access. Takes an `/et/PROJECT/REPO` reference. ```bash theme={null} entire repo grant remove REPO [GRANTEE] ``` ```bash theme={null} entire repo grant remove /et/acme/web github:alice ``` ## Continue With > **[repo edit](/cli-reference/repo#entire-repo-edit)** > > Make a repository readable by all authenticated Entire users. > **[Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions)** > > Understand GitHub-synced access for mirrors. # entire-graph Source: https://docs.entire.com/cli-reference/graph Search and analyze your codebase from the Entire CLI. entire-graph is an installable [plugin](/cli-reference/plugin) for the [Entire CLI](/cli-reference) that gives your coding agent a map of your codebase. It helps your agent find the right code, understand how it connects, and see what a change could affect before it starts editing. Install entire-graph before running `entire graph`: ```bash theme={null} entire plugin install graph ``` Then run entire-graph commands with: ```bash theme={null} entire graph COMMAND [flags] ``` Run `entire graph help` to see every command in your installed version, and `entire graph COMMAND --help` for command-specific flags. Pass `--repo .` when you run these outside an Entire session. ## graph setup Write `.entire/agent-guide.md`, add managed blocks to `AGENTS.md` and `CLAUDE.md`, and register the Claude Code SubagentStart hook in the per-user `.claude/settings.local.json` (skip the hook with `--no-claude-hook`). Replaces the removed `init-agents` command. ```bash theme={null} entire graph setup [--repo PATH] [--strict | --normal] [--no-claude-hook] ``` See [Install and Enable entire-graph](/guides/graph/set-up-graph) for the complete setup workflow. ## graph agent-guide Print the coding-agent guide that `setup` installs. ```bash theme={null} entire graph agent-guide ``` ## graph index Build a committed-tree cache before running a batch of `--head` queries. The default profile is `full`. ```bash theme={null} entire graph index --repo . [flags] ``` ## graph capabilities Report supported languages, parsing coverage, relation types, and features as JSON. ```bash theme={null} entire graph capabilities --json ``` ## graph query Return ranked source regions for a plain-language description of a task or bug. ```bash theme={null} entire graph query --repo . --profile full --query "token refresh returns 401" ``` You can also pass the text as the final argument instead of using `--query`: ```bash theme={null} entire graph query --repo . --format text "token refresh returns 401" ``` Query reads the working tree by default, so results include uncommitted changes. Use `--head` to search the committed tree instead. Results fit within a byte budget. Top results include full function bodies, while later results may contain only locations. Use `--max-context-bytes` to change the total. | Flag | Description | | - | - | | `--query TEXT` | The task or bug in one plain sentence. Required unless you pass the text as the final argument. | | `--top-k N` | Number of results. Default is `10`. | | `--format text\|json\|ndjson\|agent` | Default is `json`. `text` is tiered for reading, `agent` is compact. | | `--profile syntax-only\|fast\|full` | Parsing depth. Default is `fast`, but the installed agent guide asks for `full`, which activates the call graph. | | `--deep` | Also run the exhaustive BM25 pass and fuse it in. Slower, and reads every eligible file. | | `--head` | Search the committed tree instead of the working tree. | | `--max-context-bytes N` | Output byte budget. `0` removes the bound. Default is `24576`. | Each result includes a `signals` array that explains why it ranked, such as `path`, `body`, `symbol-name`, or `graph:callers`. ## graph impact Show callers, callees, type consumers, data flows, related files, and same-container symbols for one symbol. ```bash theme={null} entire graph impact --repo . --symbol Router.Match ``` Impact reads the working tree by default. Use `--head` to inspect the committed tree instead. ```text theme={null} Index: cache-hit (64ms) | Query: 0ms | Total: 64ms Impact: Router.Match (mux.go:151) def=151 span=151-182 [method in Router] Blast radius: 1 caller (1 direct, 0 transitive), 0 callees, 3 type consumers, 1 data flow, 7 co-change files, 29 siblings. Callers (1 direct, 0 transitive; who breaks if behavior changes): - Router.ServeHTTP (mux.go:203, def :188) ``` | Flag | Description | | - | - | | `--symbol NAME\|FILE:LINE` | Symbol to analyze. Required. | | `--depth 1\|2` | Caller traversal depth. Default is `2`. | | `--limit N` | Max entries per section. Default is `15`. | | `--exclude-tests` | Drop test-only entries. | | `--file`, `--line`, `--kind` | Disambiguate an ambiguous name. | Text output begins with `Index: cache-hit` or `Index: cache-miss`. ## graph neighbors Show direct relationships for one symbol, filtered by relation and direction. ```bash theme={null} entire graph neighbors --repo . --symbol validateToken --relation CALLS --direction in ``` Neighbors reads the working tree by default. Use `--head` to inspect the committed tree instead. | Flag | Description | | - | - | | `--symbol NAME\|FILE:LINE` | Symbol to inspect. Required. | | `--relation TYPE` | Relation family to follow. Default is `CALLS`. | | `--direction both\|in\|out` | `in` is callers, `out` is callees. Default is `both`. | | `--depth 1\|2` | Hops to traverse. Default is `1`. | | `--limit N` | Max neighbors per direction. Default is `20`. | | `--internal-only` | Drop unresolved external endpoints. | Text output begins with `Index: cache-hit` or `Index: cache-miss`. ## graph def Show a symbol's declaration. For a type, include its fields, methods, and implementations. ```bash theme={null} entire graph def RouteMatch --repo . ``` This command reads the working tree by default. Use `--head` to inspect the committed tree instead. ## graph explain Read a build or test failure from standard input and append the declarations of the symbols it names. ```bash theme={null} go test ./... 2>&1 | entire graph explain --repo . ``` Explain reads the working tree by default, so its declarations match the code that produced the failure. Use `--head` to inspect the committed tree instead. ## graph commit List entity-level changes in a commit relative to its first parent, including added, removed, renamed, signature-changed, and body-changed symbols. ```bash theme={null} entire graph commit [REV] [flags] ``` Each change includes an estimated dependent count. ## graph diff List entity-level changes between two Git references. `analyze` is an alias for this command. ```bash theme={null} entire graph diff --base BASE --head HEAD [flags] ``` ## graph checkpoint Analyze the commit associated with an [Entire checkpoint](/guides/sessions/overview#what-is-a-checkpoint). ```bash theme={null} entire graph checkpoint CHECKPOINT_ID [flags] ``` ## graph verify Run a test command and report which tests changed state. ```bash theme={null} entire graph verify --repo . --test "COMMAND" [flags] ``` > [!WARNING] > > `entire graph verify` executes the command you give it, with your privileges. So does `--setup`. Pass only commands you would run yourself. Record a baseline on a clean tree to distinguish existing failures from failures introduced by a change: ```bash theme={null} entire graph verify --repo . --test "pytest tests/" --record-baseline /tmp/base.json # make your edit entire graph verify --repo . --test "pytest tests/" --pre-edit-baseline /tmp/base.json ``` ## graph snapshot Export the complete graph as NDJSON, including files, external endpoints, symbols, relations, and a summary. ```bash theme={null} entire graph snapshot --repo . --format ndjson [flags] ``` Snapshot reads the committed tree by default. Use `--worktree` to include uncommitted changes. It also supports `--format compact-ndjson`. ## graph symbols Export symbol records as NDJSON. ```bash theme={null} entire graph symbols --repo . --format ndjson [flags] ``` Symbols reads the committed tree by default. Use `--worktree` to include uncommitted changes. Use `query` or `def` for targeted lookups because this command does not filter by name. ## graph edges Export relation records as NDJSON. Filter the output with `--to`, `--from`, and `--relation`. ```bash theme={null} entire graph edges --repo . --format ndjson [flags] ``` Edges reads the committed tree by default. Use `--worktree` to include uncommitted changes. ## graph snapshot-query Query a saved compact snapshot without rebuilding the graph. ```bash theme={null} entire graph snapshot --repo . --format compact-ndjson > graph.compact.ndjson entire graph snapshot-query --input graph.compact.ndjson --symbol Cache.Refresh ``` ## graph doctor Report the resolved repository, Entire environment variables, plugin data directory access, and whether network access is disabled. ```bash theme={null} entire graph doctor [--json] ``` `doctor --assert` is a preflight. It parses a command line against your installed binary and tells you whether it would be rejected, without running anything: ```bash theme={null} entire graph doctor --assert "query --profile full --top-k 10 --format text" ``` ## graph health Report how completely entire-graph indexed the committed tree, including when the result is healthy. ```bash theme={null} entire graph health [--repo PATH] [--json] [--refresh] ``` The report lists flagged source files and their percentage of the total, the 5% threshold at which coverage counts as degraded, a breakdown by language and diagnostic type, and the affected files with parser diagnostic locations. Documentation, configuration, and data files are not counted as source files. Files skipped on purpose, such as oversized or minified files, are listed separately. A parser diagnostic means entire-graph could not fully analyze a file. It does not mean the source code is invalid. Health always uses the committed tree at `HEAD` and the `full` profile, so it does not include uncommitted changes. It reuses a matching index or builds one first. | Flag | Description | | - | - | | `--json` | Print structured health JSON instead of text. | | `--refresh` | Rebuild the index even when a matching one exists, and invalidate derived query caches. | | `--profile syntax-only\|fast\|full` | Index profile. Default is `full`. | | `--ignore-file PATH` | Extra exclude rules in gitignore syntax. Repeatable. | | `--include-file PATH` | Re-include ignored paths. Repeatable. | Use `doctor` to check the environment and `health` to check index coverage. ## graph version Print the installed entire-graph plugin version. Add `--json` to include the provider name. ```bash theme={null} entire graph version [--json] ``` ## graph stats Compare entire-graph usage with grep and file reads in local coding-agent transcripts, including an estimated token saving. ```bash theme={null} entire graph stats [flags] ``` > [!NOTE] > > `stats` reads local coding-agent session transcripts from disk. It is for humans, not part of the agent workflow, and the installed guide tells agents not to run it unless asked. ## Continue with > **[Use entire-graph with Your Coding Agent](/guides/graph/use-graph)** > > Learn what to ask and what happens after you prompt your agent. > **[Install and Enable entire-graph](/guides/graph/set-up-graph)** > > Install the plugin and turn it on for a repository. > **[entire-graph Troubleshooting](/guides/graph/troubleshooting)** > > Fix install, adoption, and cache problems. > **[entire-graph Overview](/guides/graph/overview)** > > Understand what entire-graph is for. > **[entire-graph Repository](https://github.com/entireio/entire-graph)** > > Browse the source and the full reference docs. # help Source: https://docs.entire.com/cli-reference/help Display help information about any command. Display help information about any command. ```bash theme={null} entire help [COMMAND] ``` | Argument | Description | | - | - | | `command` | Optional. The command to get help for. | ```bash theme={null} # Show general help entire help # Get help for a specific command entire help enable entire enable --help ``` ## Print the Command Tree Pass `-t` to print every command and subcommand as a tree, with its one-line description: ```bash theme={null} entire help -t ``` ```text theme={null} entire ├── activity - Show your activity overview ├── agent - Manage agent integrations (add, remove, list) │ ├── add - Install hooks for an agent │ ├── list - List installed and available agents │ └── remove - Uninstall hooks for an agent ... ``` > [!NOTE] > > For output aimed at coding agents rather than people, use [`entire agent-help`](/cli-reference/agent-help), which generates its command map from the installed binary and supports `--json`. # import Source: https://docs.entire.com/cli-reference/import Import pre-existing local agent transcripts as read-only checkpoints. Import pre-existing local agent transcripts for the current repository as read-only checkpoints. ```bash theme={null} entire import AGENT [flags] ``` > [!NOTE] > > `entire import` is experimental. It appears under **Experimental commands** in developer and nightly builds, but is hidden from top-level help in stable releases. It remains runnable in all builds and appears in [`entire labs`](/cli-reference/labs). Run `entire import --help` to see supported agents. ## Supported Agents | Agent | Command | | - | - | | Claude Code | `entire import claude-code` | | Codex | `entire import codex` | | Copilot CLI | `entire import copilot-cli` | | Cursor | `entire import cursor` | | Factory | `entire import factoryai-droid` | | Pi | `entire import pi` | ## Flags | Flag | Description | | - | - | | `--dry-run` | Report what would be imported without writing checkpoints | | `--path DIRECTORY` | Override the transcript directory to import from | | `--session ID` | Import only this session ID. Repeatable. | ## Examples Check what would be imported: ```bash theme={null} entire import claude-code --dry-run ``` Import Claude Code transcript history: ```bash theme={null} entire import claude-code ``` Import a specific Codex session: ```bash theme={null} entire import codex --session SESSION_ID ``` Import from a custom transcript directory: ```bash theme={null} entire import claude-code --path TRANSCRIPT_DIRECTORY ``` ## Behavior `entire import` scans the agent's local transcript store for the current repository and imports history from the past month. Imported checkpoints are: * read-only * searchable * explainable * idempotent, so already-imported turns are skipped * not rewindable * not linked to a Git commit ## Continue With > **[Import Past Sessions](/guides/sessions/import-past-agent-history)** > > Follow the guide for importing past local agent sessions. > **[Search](/cli-reference/search)** > > Search imported checkpoints and other Entire history. # investigate Source: https://docs.entire.com/cli-reference/investigate Run a multi-agent investigation from a prompt, seed document, issue, or PR. entire-investigate is an installable [plugin](/cli-reference/plugin) for the Entire CLI. It runs a multi-agent investigation: agents take turns appending findings, evidence, and analysis to a shared findings document until quorum is reached. Install it before running `entire investigate`: ```bash theme={null} entire plugin install investigate ``` Running `entire investigate` without the plugin offers to install it, and reports `the entire-investigate plugin is not installed` in a non-interactive run. ```bash theme={null} entire investigate [SEED_DOC] [flags] entire investigate SUBCOMMAND ``` `entire investigate` is experimental while the workflow is still being refined. Its flags are unchanged from when the command shipped in the CLI itself. > [!NOTE] > > Settings move with the command. Copy any old `investigate` settings object into `.entire/investigate.local.json`; a legacy `investigate` block in `.entire/settings.json` is ignored. ## Inputs Use one of these inputs: | Input | Description | | - | - | | `SEED_DOC` | Path to a starting findings file | | `--issue-link URL` | GitHub issue or pull request URL resolved through `gh` | When neither input is supplied and the multi-agent picker opens, the picker collects an investigation prompt that becomes the topic for the run. ## Flags | Flag | Description | | - | - | | `--agents AGENTS` | Override configured agents with a comma-separated list | | `--max-turns N` | Per-agent turn budget. Defaults to `2`. | | `--quorum N` | Approvals needed to terminate. `0` means all agents. | | `--continue RUN_ID` | Resume an existing run | | `--edit` | Re-open the investigate config picker | | `--findings` | Browse local investigation manifests | | `--allow-untrusted-seed` | Required for non-interactive `--issue-link` investigations because the seed is attacker-influenced GitHub content | ## Subcommands | Subcommand | Description | | - | - | | `show RUN_ID` | Print a saved investigation's summary and findings | | `fix RUN_ID` | Launch a coding agent with the run's findings as grounded context | | `clean RUN_ID` | Delete a saved investigation. Add `--force` to skip the confirmation prompt. | | `clean --all` | Delete all saved investigation artifacts | ## Examples ```bash theme={null} entire investigate leaderboard-route-investigation.md --max-turns 1 entire investigate --findings entire investigate show RUN_ID entire investigate fix RUN_ID entire investigate clean RUN_ID ``` ## Continue With > **[Investigate Why Code Exists](/learn/investigate-why-code-exists)** > > Walk through a complete provenance investigation. > **[plugin](/cli-reference/plugin)** > > Install, list, and upgrade Entire plugins. # labs Source: https://docs.entire.com/cli-reference/labs Explore experimental Entire workflows. Explore experimental Entire workflows. ```bash theme={null} entire labs ``` This command lists newer Entire workflows that are available to try while they are still being refined. Use it to discover experimental commands and see where to find their command-specific help. The set changes as workflows graduate, so run `entire labs` for what your installed CLI offers. | Command | Purpose | | - | - | | [`entire review`](/cli-reference/review) | Run a multi-agent review against a branch | | [`entire import claude-code`](/cli-reference/import) | Import existing Claude Code transcripts as local, read-only history | | [`entire tokens`](/cli-reference/tokens) | Analyze token usage diagnostics | | [`entire tokens profile`](/cli-reference/tokens#tokens-profile) | Aggregate token usage across committed checkpoints | | [`entire session tokens`](/cli-reference/session#session-tokens) | Show token usage and recommendations for a session | | [`entire blame`](/cli-reference/blame) | Show which lines came from Entire checkpoints | | [`entire why`](/cli-reference/why) | Show why a line exists | | [`entire experts`](/cli-reference/experts) | Show agent, Skill, and tool provenance for files or topics | ```bash theme={null} # List experimental workflows entire labs # Open help for one of them entire review --help ``` > [!NOTE] > > `entire labs` is a discovery command. It does not run the listed workflows as nested subcommands. For example, use `entire review --help`, not `entire labs review --help`. # login Source: https://docs.entire.com/cli-reference/login Log in to Entire. Log in to Entire. ```bash theme={null} entire login [flags] ``` By default this opens a browser redirect flow. If Entire is running interactively, it prompts before opening the approval URL automatically. With no interactive terminal, over SSH, or on a Linux or BSD machine with no graphical display, `entire login` uses the device-code flow instead. It prints an approval URL and a code that you enter in a browser on any machine. Use `--device` to choose this flow explicitly. | Flag | Description | | - | - | | `--device` | Use the device-code flow, entering a code in your browser, instead of the default browser redirect. | | `--server URL` | Login server to authenticate against. Rarely needed; the default serves all standard accounts. Defaults to `https://auth.entire.io`. | ```bash theme={null} # Device-code flow, for a remote host or container entire login --device ``` > [!NOTE] > > A completed login is saved as a [context](/cli-reference/auth#login-contexts): a named pairing of login server and identity, with its tokens in your operating system's credential store. Logging in again as the same identity updates that context in place. Run [`entire auth contexts`](/cli-reference/auth#auth-contexts) to see them all. ## Machines with No OS Keyring Tokens are stored in your operating system's credential store: macOS Keychain, Linux Secret Service, or Windows Credential Manager. This also applies to device-code logins on headless machines, so no other setup is needed when a keyring is available. If the machine has no usable keyring, `entire login` fails with a `save login` error, often `failed to unlock correct collection` on Linux. In that case, use the file-backed token store: ```bash theme={null} ENTIRE_TOKEN_STORE=file entire login ``` Tokens are written with `0600` permissions to `tokens.json` in your Entire config directory (`~/.config/entire` by default). Override the location with `ENTIRE_TOKEN_STORE_PATH`. Set `ENTIRE_TOKEN_STORE=file` in your shell profile or environment so later commands read from the same store. Entire never switches to file storage automatically. Use the keyring when available, since the file stores your tokens in plain text. ## CI and Automation Where nobody is at a browser, such as a CI runner, a remote VM, or a cloud coding agent's sandbox, pick the setup that matches whether the machine keeps its files between runs. ### Machines That Keep Their Files On a self-hosted runner, a long-lived VM, or a container with a persistent home directory, log in once with the device-code flow: ```bash theme={null} entire login --device ``` Approve the printed code from any browser. The stored login refreshes itself, so later runs need no further setup. If the machine has no usable keyring, add `ENTIRE_TOKEN_STORE=file`. The login is then stored on disk, so keep the config directory on persistent storage, or set `ENTIRE_TOKEN_STORE_PATH` to a file on persistent storage. Don't copy a stored login to another machine. Each refresh replaces the stored refresh token and invalidates the old one, so two copies refreshing the same login can sign both out. ### Fresh Environments on Every Run When each run starts from a clean environment, pass a token through `ENTIRE_TOKEN` instead of logging in: ```bash theme={null} ENTIRE_TOKEN= entire ... ``` `ENTIRE_TOKEN` bypasses stored credentials. The CLI uses the token as-is, derives the control-plane endpoint from it, and never writes it to disk. It is never refreshed, so it must still be valid when the command runs: | Token | Where it comes from | Valid for | | - | - | - | | Login token | [`entire auth token`](/cli-reference/auth#auth-token) on a machine where you're logged in | 8 hours | | Service-account session | Issued for a service account by a configured workload-identity integration | 30 minutes by default | A login token acts as you and expires after 8 hours, so it suits short-lived jobs, not a standing setup. Long-lived API keys for cloud agents and other automation aren't available yet. > [!NOTE] > > Reading Entire data, such as Trails, findings, or API responses, only needs the CLI installed and authenticated. Running `entire enable` and installing agent hooks are only needed to capture an agent's sessions. # logout Source: https://docs.entire.com/cli-reference/logout Log out of Entire. Log out of every saved login. ```bash theme={null} entire logout [flags] ``` For each saved [login context](/cli-reference/auth#login-contexts), this ends every CLI session on that login server, other machines included, and removes the login from this machine. Nothing narrows it. An explicit `--context` is refused rather than ignored, and `ENTIRE_CONTEXT` is ignored. Press Ctrl-C to stop the sweep partway. Browser and web sessions stay signed in unless you pass `--everywhere`. | Flag | Description | | - | - | | `--everywhere` | Also end browser and web sessions on each login server. A browser is signed out on its next request, and the web app once its access token expires. | ```bash theme={null} # Log out of every saved login, CLI sessions only entire logout # Also end browser and web sessions entire logout --everywhere ``` > [!NOTE] > > Against an older login server, a plain `entire logout` falls back to revoking only the current session. # mcp Source: https://docs.entire.com/cli-reference/mcp Run Entire as a Model Context Protocol server over stdio. Run a Model Context Protocol (MCP) server over stdio. ```bash theme={null} entire mcp ``` `entire mcp` is hidden from `entire --help`, but it is a normal command and runs wherever the CLI is installed. Configure an MCP host to launch `entire mcp` as a stdio server. It exposes Entire's `agent_help` and `entire_status` as MCP tools, so an agent without a hook or context-injection channel can still discover and use Entire. The server is read-only and speaks newline-delimited JSON-RPC 2.0. > [!NOTE] > > This does not replace lifecycle hooks. An MCP host learns what Entire can do and what the repository's state is, but session capture still comes from the hooks that [`entire enable`](/cli-reference/enable) installs. See [Agents](/agents/overview) for the integration paths. ## Tools | Tool | Description | | - | - | | `agent_help` | The command map for the installed CLI, the same content as [`entire agent-help --json`](/cli-reference/agent-help). Takes an optional `command` argument naming a subcommand path, space-separated, such as `checkpoint` or `repo mirror add`, to drill into one command. | | `entire_status` | The current repository's Entire status, byte-identical to [`entire status --json`](/cli-reference/status). It returns JSON, not the human-readable table. | ## Configure a Host Most hosts take a command and arguments. Point yours at the `entire` binary with the `mcp` subcommand: ```json theme={null} { "mcpServers": { "entire": { "command": "entire", "args": ["mcp"] } } } ``` The exact file and schema depend on the host. Use an absolute path to `entire` if the host does not inherit your shell's `PATH`. ## Continue With > **[Agents](/agents/overview)** > > Compare hooks, context injection, and MCP as integration paths. > **[agent-help](/cli-reference/agent-help)** > > See the command map this server exposes. # org Source: https://docs.entire.com/cli-reference/org Manage Entire organizations. Manage Entire organizations. ```bash theme={null} entire org COMMAND ``` An organization owns [projects](/cli-reference/project), which in turn own [repositories](/cli-reference/repo). To manage who belongs to an org, use [`entire org grant`](/cli-reference/grant#entire-org-grant). Use an organization's name or ULID with `get` and `delete`. Most subcommands accept `--json` to print raw JSON instead of a table; `delete`, `grant remove`, and `invite revoke` do not. ## `entire org create` Create an organization. ```bash theme={null} entire org create NAME [flags] ``` | Flag | Description | | - | - | | `--region SLUG` | Jurisdiction slug. Defaults to the server's home jurisdiction. | ```bash theme={null} entire org create acme entire org create acme --region eu ``` ## `entire org list` List organizations you can see. ```bash theme={null} entire org list [flags] ``` ## `entire org get` Show an organization by name or ULID. ```bash theme={null} entire org get ORG [flags] ``` ## `entire org delete` Delete an organization by name or ULID. ```bash theme={null} entire org delete ORG [flags] ``` | Flag | Description | | - | - | | `-f, --force` | Skip the confirmation prompt. | | `-y, --yes` | Skip the confirmation prompt. Alias for `--force`. | ## `entire org invite` Invite an email address to an organization. Use this to reach people who have never signed in to Entire: [`entire org grant add`](/cli-reference/grant#entire-org-grant) needs an existing account, while an invitation reaches an address. The invitee accepts through the link in the email they receive. ### `entire org invite send` Send an invitation. ```bash theme={null} entire org invite send ORG --email EMAIL [flags] ``` Inviting an address that already has an open invitation sends the mail again and keeps the role the invitation was created with. ```bash theme={null} entire org invite send acme --email dev@example.com --role admin ``` | Flag | Description | | - | - | | `--email EMAIL` | Email address to invite. Required. | | `--json` | Output raw JSON instead of a table. | | `--role ROLE` | Role the invitation grants: `owner`, `admin`, or `member`. Defaults to `member`. | ### `entire org invite list` List an organization's invitations. ```bash theme={null} entire org invite list ORG [flags] ``` ```bash theme={null} entire org invite list acme --status all ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | | `--status STATUS` | Lifecycle state to list: `open`, `accepted`, `revoked`, `expired`, or `all`. Defaults to `open`. | ### `entire org invite revoke` Revoke the open invitation for an email address so its link stops working. ```bash theme={null} entire org invite revoke ORG --email EMAIL ``` ```bash theme={null} entire org invite revoke acme --email dev@example.com ``` | Flag | Description | | - | - | | `--email EMAIL` | Email address whose open invitation to revoke. Required. | ## Continue With > **[project](/cli-reference/project)** > > Create and manage the projects an org owns. > **[grant](/cli-reference/grant)** > > Manage org membership and access. # plugin Source: https://docs.entire.com/cli-reference/plugin Discover, install, inspect, update, and troubleshoot commands that extend the Entire CLI. CLI plugins are executables named `entire-` that add commands to Entire. For example, an executable named `entire-graph` runs when you enter `entire graph`. This system is separate from the [Agent Integration Protocol](/agents/agent-integration-protocol/overview), which uses `entire-agent-` executables to integrate coding agents. ```bash theme={null} entire plugin COMMAND ``` > [!WARNING] > > A CLI plugin is a native executable that runs with your user account's filesystem, network, and process permissions. Entire filters the environment passed to plugins, but it does not sandbox them. Install plugins only from sources you trust. ## Command Tree | Command | Purpose | | - | - | | `entire plugin browse` | Interactively browse the plugin index and install a selection. | | `entire plugin doctor` | Check managed plugins for broken entries, integrity problems, and missing dependencies. | | `entire plugin index update` | Force a refresh of the synced plugin index. | | `entire plugin info NAME` | Show index and install details for a plugin. | | `entire plugin install NAME\|URL\|PATH` | Install from the index, a repository, or a local executable. | | `entire plugin list` | List plugins installed in the managed directory. | | `entire plugin remove NAME` | Remove a managed plugin. | | `entire plugin search [TERM]` | Search the plugin index. | | `entire plugin upgrade [NAME]` | Upgrade one or all plugins installed from remote repositories. | ## Discovery and Precedence When you run a command such as `entire graph build`, Entire: 1. Checks whether `graph` is a command included with Entire. 2. Looks for an executable named `entire-graph` on `$PATH`. 3. Runs that executable with `build` as its argument and passes stdin, stdout, stderr, and its exit code through unchanged. Commands included with Entire take precedence. If you install `entire-version`, for example, `entire version` still runs the command included with Entire. Entire temporarily prepends the managed plugin directory to `$PATH` during plugin discovery. Therefore, a managed plugin takes precedence over an `entire-` executable with the same name elsewhere on your shell's `$PATH`. Entire keeps the managed directory on `$PATH` while a plugin runs so it can invoke other managed plugins. Entire reserves names beginning with `entire-agent-` for agent integrations and does not dispatch them as CLI commands. Follow the [Agent Integration Protocol](/agents/agent-integration-protocol/overview) to build or install one. ### Run an Unmanaged Plugin You do not need `entire plugin install` to run a plugin. Make the binary executable and place it anywhere on your `$PATH`: ```bash theme={null} chmod +x /path/to/entire-example entire example --help ``` Unmanaged plugins do not appear in `entire plugin list`. `entire plugin upgrade` does not update them, and you must remove them from `$PATH` manually. ## Managed Directory `entire plugin install` uses the first managed root that applies: | Environment | Managed Root | | - | - | | Override | `$ENTIRE_PLUGIN_DIR` | | Linux and macOS | `$XDG_DATA_HOME/entire/plugins`, or `~/.local/share/entire/plugins` | | Windows | `%LOCALAPPDATA%\entire\plugins`, or `~\AppData\Local\entire\plugins` | `ENTIRE_PLUGIN_DIR` must be an absolute path. Under the root, Entire uses this layout: ```text theme={null} / ├── bin/ # Executables discovered as entire- ├── data// # Durable storage available to the plugin └── pkg// ├── entire- # Binary from a remote install └── manifest.yml # Version, source, checksum, and dependencies ``` Remote installs store the downloaded binary and its provenance under `pkg/`, then link the binary into `bin/`. Local path installs link the source executable directly into `bin/`, so rebuilding the source normally updates the command immediately. When symbolic links are unavailable, Entire falls back to a hard link and then a copy. Each plugin receives: | Variable | Value | | - | - | | `ENTIRE_CLI_VERSION` | The version of the Entire CLI that launched it. | | `ENTIRE_REPO_ROOT` | The repository root, when the command runs inside a repository. | | `ENTIRE_PLUGIN_DATA_DIR` | The plugin's durable `data/` directory. The plugin creates it when needed. | Entire passes common operating system, terminal, locale, CI, proxy, SSH agent, `ENTIRE_*`, `LC_*`, and `XDG_*` variables. Entire excludes other variables by default to reduce accidental credential exposure. You can explicitly pass additional names or prefixes with `ENTIRE_PLUGIN_ENV`, for example: ```bash theme={null} ENTIRE_PLUGIN_ENV='AWS_*,GH_TOKEN' entire example ``` This filtering is defense in depth, not a security boundary: a malicious plugin can still read files and credentials available to your user account. ## Install a Plugin Install a plugin from the synced index, a git repository URL, or a local executable. ```bash theme={null} entire plugin install NAME|URL|PATH [flags] ``` | Source | Example | Behavior | | - | - | - | | Index name | `entire plugin install run` | Resolves the name through the synced plugin index. | | Repository URL | `entire plugin install https://github.com/entireio/entire-run` | Resolves a release from the repository. A URL not listed in the index requires confirmation. | | Local path | `entire plugin install ./dist/entire-run` | Links an existing executable into the managed directory. | Local paths must be explicit: include a directory separator or begin with `./`. The executable's basename must be `entire-` so Entire can derive the command name. For a remote install, Entire: 1. Uses the tag supplied with `--pin`, or tries the newest stable semantic version tag. Without `--pin`, Entire tries up to two older stable tags when newer tags lack a compatible release asset. 2. Reads `entire-plugin.yml` from that tag when the repository provides it. 3. Downloads the matching release asset over HTTPS. 4. Verifies the asset against the release's checksum manifest. 5. Stores the binary and install manifest in the managed directory. 6. Resolves and offers to install declared dependencies. Installing from a URL that is not in the plugin index asks for confirmation. Pass `--yes` to skip the prompt; a run without a terminal requires this flag for an unlisted URL. ### Checksum Verification Remote installation looks for `checksums.txt` or a supported plugin checksum filename in the release. When the manifest covers the release asset, Entire computes its SHA-256 digest and refuses the install if it does not match. Entire also records a digest of the installed binary so `entire plugin doctor` can detect later changes. If the release asset has no published checksum covering your platform, installation stops. `--allow-unverified` bypasses that requirement and records the install as unverified; `plugin doctor` continues to report it. Future upgrades preserve the original choice: a verified install cannot silently become unverified, while an unverified install remains allowed to upgrade without a new flag. > [!WARNING] > > A matching checksum proves that the downloaded bytes match the checksum published with that release. It does not prove that the repository owner, release process, or plugin code is trustworthy. Use `--allow-unverified` only after you have independently decided to trust the source and accept that the download is not authenticated by a published checksum. ### Dependencies A plugin repository can declare runtime dependencies in `entire-plugin.yml`: ```yaml theme={null} name: example description: Example Entire CLI plugin requires: - name: graph min_version: v0.4.0 ``` `min_version` accepts an optional minimum semantic version. Entire does not support version ranges. Entire resolves dependencies by name through the plugin index, including transitive dependencies. A plugin author cannot supply a dependency repository URL in `entire-plugin.yml`. Entire shows the dependencies it plans to install or upgrade and asks once for confirmation. Use `--yes` in a run without a terminal or `--no-deps` to install only the requested plugin. If a dependency already comes from a local path or your shell's `$PATH`, Entire treats it as present but cannot verify its minimum version. Run `entire plugin doctor` to inspect the resulting state. | Flag | Description | | - | - | | `--allow-unverified` | Install when no published checksum covers the release asset. | | `--force` | Replace an existing managed entry with the same name. | | `--index URL` | Use a different plugin index for this command. | | `--no-deps` | Do not install declared dependencies. | | `--pin TAG` | Install exactly this tag and skip the plugin during upgrades. | | `--yes` | Skip confirmation prompts for unlisted sources and dependencies. | ## List Managed Plugins List plugins installed in the managed directory. ```bash theme={null} entire plugin list ``` ```text theme={null} Managed plugin directory: /Users/you/.local/share/entire/plugins/bin run v0.1.0 → /Users/you/.local/share/entire/plugins/pkg/run/entire-run ``` This command does not list unmanaged `entire-` executables elsewhere on `$PATH`. ## Search the Plugin Index Search the synced plugin index. Run the command without a term to list everything available. A `*` marks a managed plugin that is already installed. ```bash theme={null} entire plugin search [TERM] [flags] ``` ```text theme={null} * run Launch one of the agents enabled for Entire in the current repository [official] upgrade Upgrade the system-installed Entire binary [official] ``` Entire caches the Git repository that contains the index. On the next index operation after the cached copy is 24 hours old, Entire attempts a refresh. If a refresh fails while you are offline, Entire uses the existing cached copy. The index URL resolves in this order: `--index`, `ENTIRE_PLUGIN_INDEX_URL`, then Entire's default index. | Flag | Description | | - | - | | `--index URL` | Use a different plugin index for this command. | ## Inspect a Plugin Show index metadata and managed install details for a plugin, including its repository, version, pin, and dependencies. ```bash theme={null} entire plugin info NAME [flags] ``` ```text theme={null} Name: run Description: Launch one of the agents enabled for Entire in the current repository Repository: https://github.com/entireio/entire-run Official: true Installed: v0.1.0 (from https://github.com/entireio/entire-run) ``` | Flag | Description | | - | - | | `--index URL` | Use a different plugin index for this command. | ## Browse the Plugin Index Browse the plugin index in an interactive picker and install a selection. ```bash theme={null} entire plugin browse [flags] ``` The picker shows each plugin's name and description. Before downloading anything, Entire shows the repository that provides the binary and asks you to confirm. > [!NOTE] > > This command needs a terminal. Use `entire plugin search` and `entire plugin install NAME` in scripts and runs without a terminal. | Flag | Description | | - | - | | `--index URL` | Use a different plugin index for this command. | ## Upgrade Plugins Upgrade one plugin installed from a remote repository, or use `--all` to upgrade every eligible plugin. Entire tries the newest stable semantic version first and uses the same release asset fallback as installation. ```bash theme={null} entire plugin upgrade NAME entire plugin upgrade --all ``` Entire cannot upgrade local path installs because they have no remote install manifest. Pinned plugins stay at their selected version until you reinstall them without `--pin`. | Flag | Description | | - | - | | `--all` | Upgrade every eligible plugin installed from a remote repository. | ## Remove a Plugin Remove a plugin from the managed directory. ```bash theme={null} entire plugin remove NAME [flags] ``` If another managed plugin declares the target as a dependency, Entire refuses removal unless you pass `--force`. This command does not remove unmanaged executables elsewhere on `$PATH`. | Flag | Description | | - | - | | `--force` | Remove a plugin even when other managed plugins depend on it. | ## Diagnose Plugin Problems Check managed plugins for: * broken managed entries * dangling links to local paths * missing or outdated dependencies * unverified installs * changes to a binary installed from a remote repository * the macOS quarantine attribute ```bash theme={null} entire plugin doctor ``` ```text theme={null} All plugins healthy. ``` The command prints a suggested fix for each actionable problem and exits unsuccessfully when it finds issues. ## Update the Plugin Index Force a refresh of the plugin index from its Git repository. ```bash theme={null} entire plugin index update [flags] ``` Use this command when `plugin search` does not show a newly published plugin or when you need to refresh the index before the cached copy becomes stale. | Flag | Description | | - | - | | `--index URL` | Refresh a different plugin index. | ## Troubleshooting ### `entire NAME` Reports an Unknown Command 1. Confirm the executable is named `entire-NAME`, including the `entire-` prefix. 2. Run `entire plugin list` for a managed install. 3. For an unmanaged install, run `command -v entire-NAME` on Linux or macOS, or `where entire-NAME` on Windows. 4. On Linux or macOS, make the file executable with `chmod +x /path/to/entire-NAME`. 5. Run `entire plugin doctor` to check managed entries. ### The Wrong Copy Runs Entire prepends the managed `bin/` directory during discovery, so it wins over matching executables elsewhere on `$PATH`. Run `entire plugin list` to see the managed entry. Remove it with `entire plugin remove NAME` if you intend to use the copy from your shell's `$PATH`. If the name matches a command included with Entire, Entire runs that command. Rename the plugin executable and invoke it under the new name. ### A Plugin Is Missing from Search Refresh and search the index: ```bash theme={null} entire plugin index update entire plugin search NAME ``` If the plugin is not indexed, install its repository URL directly. Review the repository before accepting the unlisted source prompt. ### Installation Needs a Terminal An unlisted repository URL and dependency installation require confirmation. In CI or another environment without a terminal, review the source and its `entire-plugin.yml` dependencies first, then add `--yes`. ### Checksum Verification Fails Do not bypass a checksum mismatch. A mismatch means the downloaded asset differs from the published digest. If no checksum covers your platform, ask the plugin author to publish one. `--allow-unverified` is an explicit choice for a missing checksum, not a remedy for a mismatch. ### A Local Plugin Does Not Update Local installs use a symbolic link when the platform allows it, so rebuilding the source updates the command. On systems that require the hard link or copy fallback, reinstall with `--force` after rebuilding: ```bash theme={null} entire plugin install ./dist/entire-example --force ``` ### Dependencies Are Missing or Outdated Run `entire plugin doctor` and follow its suggested install or upgrade commands. Reinstall the parent plugin without `--no-deps` if you want Entire to plan the transitive dependency set again. # project Source: https://docs.entire.com/cli-reference/project Manage Entire projects. Manage Entire projects. ```bash theme={null} entire project COMMAND ``` A project is owned by an [organization](/cli-reference/org) or by an account, and in turn owns [repositories](/cli-reference/repo). To manage who can reach a project, use [`entire project grant`](/cli-reference/grant#entire-project-grant). Use a project's name or ULID with `get` and `delete`. Most subcommands accept `--json` to print raw JSON instead of a table; `delete` and `grant remove` do not. ## `entire project create` Create a project owned by an org or an account. ```bash theme={null} entire project create NAME --owner OWNER [flags] ``` `--owner` names the owning org (by name or ULID) or account (as `github:handle`, or by ULID). `--owner-type` selects which of the two you mean. | Flag | Description | | - | - | | `--owner OWNER` | Owning org (name or ULID), or account (`github:handle` or ULID). Required. | | `--owner-type TYPE` | Owner kind: `org` or `account`. Defaults to `org`. | | `--region SLUG` | Jurisdiction slug. Defaults to the server's home jurisdiction. | ```bash theme={null} # Project under an org, by name entire project create widgets --owner acme --owner-type org # Project owned by an account, by handle entire project create widgets --owner github:alice --owner-type account ``` ## `entire project list` List projects you can see. ```bash theme={null} entire project list [flags] ``` | Flag | Description | | - | - | | `--name NAME` | Filter by exact project name. | | `--org ORG` | List projects owned by this org, by name or ULID. | ## `entire project get` Show a project by name or ULID. ```bash theme={null} entire project get PROJECT [flags] ``` ## `entire project delete` Delete a project by name or ULID. ```bash theme={null} entire project delete PROJECT [flags] ``` | Flag | Description | | - | - | | `-f, --force` | Skip the confirmation prompt. | | `-y, --yes` | Skip the confirmation prompt. Alias for `--force`. | ## Continue With > **[repo](/cli-reference/repo)** > > Create and manage the repositories a project owns. > **[grant](/cli-reference/grant)** > > Grant and revoke project access. # recap Source: https://docs.entire.com/cli-reference/recap Summarize recent checkpoint activity. Summarize recent checkpoint activity. ```bash theme={null} entire recap [flags] ``` `entire recap` shows a time-based summary of agent and checkpoint activity. By default, it opens the interactive recap view for today. Use `--static` when you want plain terminal output, such as in a script, transcript, or docs example: ```bash theme={null} entire recap --static ``` ## Time Windows Choose the range you want to summarize: ```bash theme={null} # Today only entire recap --day # Last 7 days entire recap --week # This calendar month entire recap --month # Rolling 90 days entire recap --90 ``` ## Views Limit recap to one agent: ```bash theme={null} entire recap --agent codex ``` Choose which columns to show: ```bash theme={null} entire recap --view you entire recap --view team entire recap --view both ``` ## Flags | Flag | Description | | - | - | | `--90` | Show the rolling 90-day window. | | `--agent ID` | Show activity for one agent, or use `all`. Defaults to `all`. | | `--color MODE` | Set color output to `auto`, `always`, or `never`. Defaults to `auto`. | | `--day` | Show today only. This is the default time window. | | `--insecure-http-auth` | Allow plain HTTP auth. Local development only. | | `--month` | Show this calendar month. | | `--static` | Print static output instead of opening the interactive recap. | | `--view VIEW` | Choose which columns to show: `you`, `team`, or `both`. Defaults to `both`. | | `--week` | Show the last 7 days. | | `-h, --help` | Show help for `entire recap`. | ## Examples ```bash theme={null} # Open the interactive recap for today entire recap # Print a static recap for today entire recap --static # Print the last 7 days without color entire recap --week --static --color never # Show only your activity entire recap --view you # Show one agent's activity entire recap --agent codex --static ``` # repo Source: https://docs.entire.com/cli-reference/repo Manage Entire Repositories and GitHub mirror placements. Manage Entire Repositories. ```bash theme={null} entire repo COMMAND ``` ## Repository References Commands that take a `REPO` accept a forge-qualified reference that names where the repository lives: | Reference | Meaning | | - | - | | `/et/PROJECT/REPO` | An Entire repository in a project. | | `/gh/OWNER/REPO` | A GitHub repository that Entire mirrors. | A trailing `.git` is never part of a repository name, so `/et/PROJECT/REPO` and `/et/PROJECT/REPO.git` address the same repository. A bare `OWNER/REPO` names no forge, so Entire refuses it and suggests the qualified spellings. A GitHub URL such as `github.com/OWNER/REPO` is refused too, so that one repository has one spelling: the mirror, clone, remote, and grant commands name the `/gh/OWNER/REPO` form to use instead, while the rest report the reference they expected. Which reference a command takes depends on what it acts on: | Commands | Accepted | | - | - | | `repo clone`, `repo mirror add\|remove`, `repo remote add` | `/gh/` and `/et/` references. | | `repo view` | `/et/` and `/gh/` references, or an `entire://` clone URL. A ULID or a bare name is refused. | | `repo edit`, `repo delete`, `repo protection`, `repo visibility get` | An `/et/` path, a bare name with `--project`, or a repository ULID. A `/gh/` reference is refused by name — pass the mirror's ULID instead, since a mirror belongs to no project. | | `repo grant add`, `repo grant remove` | An `/et/` path only. A mirror's access is the upstream GitHub repository's. | | `repo grant list` | `/et/` and `/gh/` references. | > [!NOTE] > > A GitHub mirror's visibility and branch protection are the upstream repository's, managed on GitHub. `repo protection list` says so rather than returning an empty rule set. ## `entire repo create` Create a repository in a project. ```bash theme={null} entire repo create NAME [flags] ``` A name ending in `.git`, in any letter case, is refused. By default the command waits for provisioning to become active. Active means provisioning completed; later pushes or mirror creation can still fail for other reasons. If creation succeeds but readiness cannot be confirmed, the command exits nonzero and preserves the repository result. Do not create the repository again to recover. | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. Standard output carries one repository object, while progress and recovery instructions go to standard error. | | `--no-wait` | Return after creation without confirming provisioning readiness. | | `--object-format FORMAT` | Git object format: `sha1` or `sha256`. Defaults to the server default. | | `--project PROJECT` | Owning project name or ULID. Required. | | `--wait-timeout DURATION` | Time limit for project resolution, creation, and provisioning readiness. Must be positive. Defaults to `10m0s`. Applies to `--no-wait` runs too. | ## `entire repo list` List repositories in a project. ```bash theme={null} entire repo list --project PROJECT [flags] ``` By default at most 1,000 repositories are fetched, and a note on standard error says so when the project has more. Rows come in server order; this list has no local filters or sort. With `--json`, a paged response wraps rows in an `{items, nextPageToken}` envelope. | Flag | Description | | - | - | | `--all` | Fetch every repository instead of the first 1,000. Slower on large projects. | | `--json` | Output raw JSON instead of a table. | | `--limit N` | Fetch and show only the first N repositories. `0` uses the default fetch budget. | | `--no-pager` | Print directly to standard output instead of a pager. | | `--page-size N` | Fetch a single page of at most N entries, from 1 to 500, and print the resume cursor. The server may cap N further. | | `--page-token TOKEN` | Fetch the single page at this cursor, from a previous run's `nextPageToken`. | | `--project PROJECT` | Project to list, by name or ULID. Required. | ## `entire repo view` Show a repository: its name, visibility, and one row per cluster it is placed on, with that cluster's role, clone URL, and status. ```bash theme={null} entire repo view REPO [flags] ``` `REPO` names its forge, and nothing else addresses a repository here: | Form | Shows | | - | - | | `/et/PROJECT/REPO` | An Entire repository's primary cluster and each mirror of it, plus seeding progress while a mirror is being created. | | `/gh/OWNER/REPO` | A GitHub upstream, with its mirror on every cluster. This is the `mirror list` `NAME` column. | | `entire://CLUSTER/...` | The repository behind a clone URL, as `git clone` takes it. A trailing `.git`, as pasted from `git remote -v`, resolves the same repository. | The `CLUSTER` column prints the public host that `--cluster` accepts elsewhere. Primary and mirror rows share one status vocabulary, such as `ready`, `processing`, or `failed`. A state the CLI does not recognize is shown as the server reports it. A clone URL is looked up on the login server fronting its cluster, so it resolves even when that cluster belongs to another federation. Every other form is looked up on the active context's login server. This command does not wait. It exits successfully when it can read the repository, even if provisioning is still in progress or has failed. For scripting, use `--authoritative --json` and inspect `state`, where `active` means provisioning completed. Examples: ```bash theme={null} entire repo view /et/acme/web entire repo view /gh/octocat/hello-world entire repo view /et/acme/web --json entire repo view entire://aws-us-east-2.entire.io/et/acme/web ``` | Flag | Description | | - | - | | `--authoritative` | Fail rather than leave the status cell blank when the server cannot confirm provisioning state. | | `--json` | Output raw JSON instead of a table. | ## `entire repo edit` Edit a repository's settings. ```bash theme={null} entire repo edit REPO --visibility VISIBILITY [flags] ``` `--visibility public` grants read-only access to any authenticated Entire user, while push and repository management stay restricted to grantees. `--visibility private` restricts the repository to explicit grantees. The caller needs manage permission on the repository. ```bash theme={null} entire repo edit /et/my-project/my-repo --visibility private ``` | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | | `--project PROJECT` | Owning project name or ULID. Required when `REPO` is a bare name, and redundant with a `/et/PROJECT/REPO` path or a ULID. | | `--visibility VISIBILITY` | Visibility to set: `public` or `private`. Required. | ## `entire repo clone` Clone an Entire repository, a GitHub mirror, or a full `entire://` clone URL. ```bash theme={null} entire repo clone REPO [TARGET_DIR] [flags] ``` `REPO` takes one of three forms: | Form | Behavior | | - | - | | `/et/PROJECT/REPO` | An Entire repository. Entire looks up every cluster it is readable from: its home cluster and any ready native mirrors. | | `/gh/OWNER/REPO` | A GitHub mirror. Entire looks up the clusters the repository is mirrored on. | | `entire://CLUSTER/gh/OWNER/REPO` | A full clone URL, which already names the cluster. Entire passes it straight to `git clone` with no lookup, and `--cluster` is ignored. | With either reference, a single cluster is cloned directly. When the repository is readable on several, an interactive terminal prompts you to pick one. Without a terminal, an `/et/` repository falls back to its own primary cluster, while a `/gh/` mirror falls back to `aws-us-east-2.entire.io` and errors asking for `--cluster` if the mirror is not placed there. Pass `--cluster` to choose either way, or `--nearest` to let Entire measure. The optional `TARGET_DIR` is passed through to `git clone` in every case. Examples: ```bash theme={null} entire repo clone /et/my-project/example entire repo clone /gh/octocat/hello-world entire repo clone /gh/octocat/hello-world ./hello-world entire repo clone /gh/octocat/hello-world --cluster aws-us-east-2.entire.io entire repo clone /gh/octocat/hello-world --nearest entire repo clone entire://aws-us-east-2.entire.io/gh/octocat/hello-world ``` | Flag | Description | | - | - | | `--cluster HOST` | Cluster to clone from when the repository is readable on more than one. For a `/gh/` reference it may belong to another auth context. | | `--nearest` | Time a connection to each cluster and clone from the fastest, instead of prompting. It orders the prompt by distance, and replaces the no-terminal default — an `/et/` repository's primary cluster, or `aws-us-east-2.entire.io` for a `/gh/` mirror — when that default was measured and lost. Cannot be combined with `--cluster`: both choose a cluster, so Entire asks you to pass one. | The `--nearest` timing is local, and the control plane is never told where you are. Each candidate cluster does see a connection from you, where without the flag only the one you clone from would. ## `entire repo delete` Delete a repository. ```bash theme={null} entire repo delete REPO [flags] ``` | Flag | Description | | - | - | | `-f, --force` | Skip the confirmation prompt. | | `--project PROJECT` | Owning project name or ULID. Required when `REPO` is a bare name, and redundant with a `/et/PROJECT/REPO` path or a ULID. | | `-y, --yes` | Skip the confirmation prompt. Alias for `--force`. | ## `entire repo mirror add` Register a mirror placement on one or more clusters. ```bash theme={null} entire repo mirror add [REPO] [flags] ``` With no arguments, `entire repo mirror add` opens an interactive wizard to choose repositories and regions, then creates every repository and region pair in parallel and prints the clone URLs. `--cluster` requires a `REPO`. With a `REPO`, the command places it on every cluster named by `--cluster` in parallel, then waits for each to become usable. Repeat the flag or comma-separate the hosts for several. Placement is idempotent for a given repository and cluster, so naming one the repository is already on reports it rather than failing. Every cluster is attempted independently: one that fails does not stop the others, and the command exits nonzero naming the ones that did. Alongside the clone URLs, the command suggests [`entire repo remote add origin --override`](#entire-repo-remote-add) to repoint an existing checkout at the new mirror. ### GitHub and Entire Repositories | Reference | Behavior | | - | - | | `/gh/OWNER/REPO` | Mirrors the GitHub upstream. When `--cluster` is omitted, an interactive terminal offers the available clusters as a multi-select, and a non-interactive run defaults to `aws-us-east-2.entire.io`. | | `/et/PROJECT/REPO` | Places replicas of an Entire repository and waits for each to be seeded. A native mirror goes in a region other than the repository's own, so only those clusters are offered and `--cluster` has no default. A non-interactive run must name one. | Examples: ```bash theme={null} entire repo mirror add entire repo mirror add /gh/octocat/hello-world entire repo mirror add /gh/octocat/hello-world --cluster aws-us-east-2.entire.io entire repo mirror add /gh/octocat/hello-world --cluster aws-us-east-2.entire.io,aws-eu-central-1.entire.io entire repo mirror add /et/acme/web --cluster aws-eu-central-1.entire.io ``` | Flag | Description | | - | - | | `--cluster HOST` | Cluster host to mirror onto. Repeat the flag or comma-separate hosts for several. A terminal offers a multi-select when this is omitted; for a `/gh/` reference other runs use `aws-us-east-2.entire.io`. | | `--no-wait` | Return once the placements are registered, without waiting for the initial clone. | | `--timeout DURATION` | How long to wait for mirror request submission, placement, and clone readiness. `0` waits indefinitely. Defaults to `30m0s`. | ## `entire repo mirror list` List repositories you can see: existing mirrors and GitHub repositories you could onboard. ```bash theme={null} entire repo mirror list [flags] ``` GitHub is the default view. Pass `--forge et` for Entire repositories and where each is placed, or `--forge all` for both in one table. The `NAME` column always prints the forge-qualified reference the other commands take. Existing mirrors appear once per repository, with their clusters and status. Available GitHub repositories show access and availability instead of placement details. Sparse cells show `-`. Use [`entire repo view /gh/OWNER/REPO`](#entire-repo-view) for per-cluster clone URLs. Filters and `--sort` apply to the fetched rows, so combine them with `--all` to work over the complete list. | Flag | Description | | - | - | | `--access ACCESS` | Filter available repositories by `read`, `write`, or `admin`. | | `--all` | Fetch the complete directory instead of the first 1,000 entries. | | `--available` | Show GitHub repositories that can be onboarded. | | `--cluster HOST` | Show only repositories mirrored on this cluster, by public host as the `HOST` column of `entire cluster list` prints it. A cluster slug is refused. Drops onboardable candidates. | | `--forge FORGE` | Which repositories to list: `gh` for GitHub mirrors and onboardable GitHub repos, `et` for Entire repositories, or `all` for both. Defaults to `gh`. | | `--json` | Output raw JSON instead of a table. | | `--limit N` | Show at most `N` rows after filters and sorting. | | `--mirrored` | Show repositories with mirror placements. | | `--name NAME` | Filter by a substring of the `NAME` column, such as `acme/web` or `/gh/acme`, case-insensitively. | | `--no-pager` | Print directly to standard output. | | `--owner OWNER` | Filter by upstream owner. | | `--page-size N` | Fetch one page of `N` entries, from 1 to 500. | | `--page-token TOKEN` | Fetch one page from a previous response cursor. | | `--private[=false]` | Show private repositories, or public repositories when set to `false`. | | `--sort KEY` | Sort by a column key. Prefix the key with `-` for descending order. | | `--status STATUS` | Filter by mirror or onboarding status. | ## `entire repo mirror remove` Remove mirror placements from one or more clusters. ```bash theme={null} entire repo mirror remove REPO [flags] ``` The command removes the placements on every cluster named by `--cluster`, in parallel. Other clusters' placements of the same repository, and the repository itself, are unaffected. Removing a mirror placement does not delete or rewrite an upstream GitHub repository. There is no default cluster. Which clusters a repository is on is a property of the repository, so guessing one would delete a copy you never named. With `--cluster` omitted, a terminal offers the clusters the repository is actually mirrored on as a multi-select, with each placement's status; nothing starts ticked, so the selection doubles as the confirmation. A non-interactive run must name the clusters. An Entire repository's own primary cluster is listed but never removable — use [`entire repo delete`](#entire-repo-delete) for that. Teardown is asynchronous, so the command waits for each placement to disappear. Examples: ```bash theme={null} entire repo mirror remove /gh/octocat/hello-world entire repo mirror remove /gh/octocat/hello-world --cluster aws-eu-central-1.entire.io entire repo mirror remove /et/acme/web --cluster aws-eu-central-1.entire.io,aws-ap-south-1.entire.io ``` | Flag | Description | | - | - | | `--cluster HOST` | Cluster host to remove the mirror from. Repeat the flag or comma-separate hosts for several. A terminal offers a multi-select when this is omitted. | | `--timeout DURATION` | How long to wait for each placement to be torn down. `0` waits indefinitely. Defaults to `30m0s`. | ## `entire repo remote add` Add a Git remote that goes through Entire instead of the forge. ```bash theme={null} entire repo remote add REMOTE_NAME [REPO] [flags] ``` The repository is resolved from the current clone's remotes; pass `REPO` to name a different one. With more than one cluster to choose from, a terminal gets a picker and a script gets the repository's own cluster. `--cluster` selects one either way, the same as [`entire repo clone`](#entire-repo-clone). `REMOTE_NAME` must not already exist. As with `git remote add`, an occupied name is refused rather than repointed. The command only ever edits local Git configuration. The cluster must already serve the repository, so create the placement with [`entire repo mirror add`](#entire-repo-mirror-add) first; nothing server-side is changed. Examples: ```bash theme={null} entire repo remote add entire entire repo remote add entire --cluster aws-us-east-2.entire.io entire repo remote add entire /gh/octocat/hello-world entire repo remote add origin --override ``` | Flag | Description | | - | - | | `--cluster HOST` | Cluster host to use when the repository is on several. | | `--override` | Repoint `REMOTE_NAME` when it already exists, instead of refusing. | > [!WARNING] > > `--override` prints the URL it replaced, with any credentials redacted. That printout is the only record of the previous URL, so keep your own copy if you need it. To find a clone URL without touching Git configuration, use [`entire repo view`](#entire-repo-view), which lists the URL for each cluster. ## `entire repo protection` List, add, or remove a repository's branch-protection rules. ```bash theme={null} entire repo protection SUBCOMMAND REPO [flags] ``` Each rule names a branch pattern and a level. **protected** refuses force pushes and deletion, while fast-forward pushes stay allowed. **server-side merge only** also refuses every direct push, so the branch moves only through a merge Entire performs, such as a trail merge. A pattern is `HEAD` for the default branch, a branch name such as `main`, or a pattern with `*` and `?` wildcards such as `release/*`. > [!NOTE] > > Branch protection applies to Entire repositories only. For a GitHub mirror, `entire repo protection list` says the rules are the upstream repository's. That note is part of the table output; with `--json`, standard output is `[]` and the note goes to standard error. Every subcommand takes `--json` to print raw JSON instead of a table, and `--project PROJECT` to name the owning project when `REPO` is a bare name. ### `entire repo protection list` Show a repository's branch-protection rules. ```bash theme={null} entire repo protection list REPO [flags] ``` ### `entire repo protection add` Protect a branch, or change the level of an existing rule. ```bash theme={null} entire repo protection add REPO BRANCH [flags] ``` A new rule protects the branch from force pushes and deletion. With `--server-side-merge-only`, every direct push is refused. Re-adding a branch without the flag keeps its current level; pass `--server-side-merge-only=false` to lower it. The command prints the resulting rules. The caller needs manage permission on the repository. ```bash theme={null} entire repo protection add /et/acme/web main entire repo protection add /et/acme/web 'release/*' --server-side-merge-only ``` | Flag | Description | | - | - | | `--server-side-merge-only` | Refuse every direct push, so the branch moves only through a merge Entire performs. Omit it to keep an existing rule's level, or pass `=false` to lower it. | ### `entire repo protection remove` Remove a branch-protection rule. ```bash theme={null} entire repo protection remove REPO BRANCH [flags] ``` `BRANCH` names the rule as it was added. Removing a branch that has no rule changes nothing. The command prints the resulting rules and needs manage permission on the repository. ## `entire repo grant` Grant and revoke repository access, and list who can reach a repository. ```bash theme={null} entire repo grant add REPO [GRANTEE] --role ROLE entire repo grant list REPO entire repo grant remove REPO [GRANTEE] ``` `entire repo grant list` answers for both forges: an `/et/` reference lists the repository's grants, and a `/gh/` reference lists who can pull the mirror. `add` and `remove` take `/et/` references only, because a mirror's access follows the upstream GitHub repository. See [grant](/cli-reference/grant#entire-repo-grant) for roles, grantee syntax, and flags. ## `entire repo visibility get` Show whether an Entire repository is public or private. ```bash theme={null} entire repo visibility get REPO [flags] ``` Set visibility with [`entire repo edit --visibility`](#entire-repo-edit). | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | | `--project PROJECT` | Owning project name or ULID. Required when `REPO` is a bare name, and redundant with a `/et/PROJECT/REPO` path or a ULID. | ## Continue With > **[Mirror a GitHub Repository](/learn/mirror-a-github-repository)** > > Create a mirror and use it from Git. > **[Mirror Access and Permissions](/guides/repositories/mirror-access-and-permissions)** > > Understand GitHub-synced access, hourly collaborator sync, and offboarding. > **[project](/cli-reference/project)** > > Manage the projects that own repositories. > **[grant](/cli-reference/grant)** > > Grant and revoke repository access. # review Source: https://docs.entire.com/cli-reference/review Run a multi-agent review against a branch and consolidate the results into a final verdict. Run a multi-agent review against the current branch, or against another branch with `--target`. ```bash theme={null} entire review [PROFILE] [flags] ``` `entire review` starts reviewer agents in parallel, then uses a judge agent to consolidate their reports into a final verdict. Reviews are saved as named profiles in Entire settings. On first run, guided setup writes a profile and asks before starting agents. ## Configure a Review Profile Open the review setup flow: ```bash theme={null} entire review --configure ``` Use non-interactive flags when you want to create or update a profile from a script: ```bash theme={null} entire review --configure \ --set-agents codex,claude-code \ --set-judge codex \ --set-output local ``` This creates the default `general` profile unless you choose another profile name in the interactive setup. ## Run a Review Run a named profile: ```bash theme={null} entire review general ``` You can also select a profile with `--profile`: ```bash theme={null} entire review --profile general ``` Scope the review against a specific base branch: ```bash theme={null} entire review general --base origin/main ``` Add one-off instructions for a single run: ```bash theme={null} entire review general --prompt "Focus on auth, error handling, and missing tests." ``` Run only one reviewer from the selected profile: ```bash theme={null} entire review general --agent codex ``` Review a branch other than the one you are on, without switching your checkout. Entire checks it out in a worktree and reviews it there: ```bash theme={null} entire review general --target feature/token-refresh --cleanup-worktree ``` ## Flags | Flag | Description | | - | - | | `--configure` | Set up a review profile. Shows available agents and profiles unless paired with `--set-*` flags. | | `--set-agents AGENTS` | With `--configure`, set comma-separated reviewer agents for the profile. | | `--set-judge AGENT[=MODEL]` | With `--configure`, set the consolidating judge. | | `--set-output MODE` | With `--configure`, set where the verdict is delivered: `local` or `trail`. Defaults to `local`. | | `--local` | With `--configure`, save to `.entire/settings.local.json` instead of shared `.entire/settings.json`. | | `--set-task TEXT` | With `--configure`, set the profile's canonical task text. | | `--set-model AGENT=MODEL` | With `--configure`, set a model for a reviewer agent. Repeatable. | | `--set-slot AGENT[=MODEL]` | With `--configure`, set one reviewer slot. Repeatable; the same agent or model can appear more than once. | | `--edit` | Reopen the advanced review profile skill picker. | | `--findings [HANDLE]` | Browse local review findings. Pass a handle to print one saved run. | | `--agent NAME` | Run one reviewer from the selected profile. | | `--agents` | List reviewer agents available for the selected profile. | | `--model NAME` | Override the model for the selected `--agent` reviewer. Requires `--agent`. | | `--models` | List the models each review agent advertises. Optionally combine with `--agent NAME`. | | `--profile NAME` | Select a review profile. You can also pass the profile name as the positional argument. | | `--prompt TEXT` | Add one-off instructions for this review run. | | `--timeout DURATION` | Time limit for each reviewer and the judge. By default, reviewers have no timeout and the judge has a 20-minute timeout. | | `--base REF` | Scope the review against a Git ref instead of the default mainline ref. Defaults to the first existing ref from `origin/HEAD`, `origin/main`, `origin/master`, `main`, or `master`. | | `--target REF` | Check out a branch in a worktree and run the review there. Accepts a branch name, a trail ID, or an Entire trail URL. | | `--cleanup-worktree` | Remove a newly created `--target` worktree after a successful review. Interactive runs ask when you omit this flag. | | `--list` | List configured review profiles with their reviewers and judge. | | `-h, --help` | Show help for `entire review`. | A reviewer that exceeds the timeout is canceled and marked failed; the other reviewers and the judge continue. If the judge times out or fails, the review ends without a verdict. > [!NOTE] > > `entire review --findings` only browses local findings. It does not apply fixes. ## Attach an Existing Review To tag an already-finished session as a review, use [`entire session attach`](/cli-reference/session#session-attach) with `--review`: ```bash theme={null} entire session attach SESSION_ID --review ``` ## Examples ```bash theme={null} # Configure a review profile entire review --configure # Configure a profile without the interactive setup entire review --configure --set-agents codex,claude-code --set-judge codex --set-output local # Run the general profile entire review general # Review a stacked branch against its parent entire review general --base origin/my-parent-branch # Run one configured reviewer entire review general --agent codex # Browse local findings entire review --findings # List configured profiles entire review --list ``` ## Continue with > **[Review and Recap Agent Work](/learn/review-and-recap-agent-work)** > > Configure reviewers, run a review, and inspect recent activity in one tutorial. > **[Review Profiles](/guides/configuration/review-profiles)** > > Configure shared and local review behavior. # runner Source: https://docs.entire.com/cli-reference/runner Set up and tune this repository's trail runners. Manage the trail runner configs in `.entire/runners/`. ```bash theme={null} entire runner SUBCOMMAND ``` `entire runner` is experimental and is hidden from the top-level help. A [runner](/glossary#runner) scores and reviews a branch's changes; this command manages the per-repository set: risk, confidence, drift, security, review, and others. ## runner setup Create and tailor this repository's trail runners. ```bash theme={null} entire runner setup [RUNNER] [flags] ``` `setup` creates the default runner set in a repository that has none, and tailors the generic templates to this repository using gathered signal: its documentation and structure, merged pull requests and issues, checkpoint churn hotspots, and past trail findings. In a terminal with no flags, `setup` asks whether you want the generic defaults or defaults tailored to this repository. Otherwise, name the action up front with one of `--yes`, `--defaults-only`, `--print-prompt`, or `--dry-run`. A non-interactive run requires one of them. `--yes` and `--dry-run` each call your configured summary provider once. With no provider configured and several agents installed, you are asked which to use; `--agent NAME` names one for this run instead and saves nothing. Pass a runner name, such as `risk` or `trail-risk`, to tune only that runner. | Flag | Description | | - | - | | `--agent NAME` | Text-generation agent to tailor with for this run, such as `codex`. Skips the provider choice and saves nothing. Only applies to runs that tailor: `--yes`, `--dry-run`, or choosing to tailor at the prompt. | | `--debug-dir DIRECTORY` | Write the assembled prompt as `prompt.txt` and, when a provider runs, its raw response as `response.txt`, to this directory. | | `--defaults-only` | Create the generic default runners and stop. No tailoring, and no provider call. | | `--dry-run` | Show the tailoring as a diff and write nothing. | | `--limit N` | How many recent pull requests, issues, and trails to sample. Defaults to `20`. | | `--print-prompt` | Create the default runners if missing, then print the tailoring prompt for your own agent to run instead of calling a provider. | | `--sources SOURCES` | Comma-separated data sources to gather: `repo`, `prs`, `checkpoints`, `trails`, or `all`. Defaults to `all`. | | `-y, --yes` | Create the default runners if missing, then tailor them to this repository in place. | ```bash theme={null} # Create the default runners and tailor them to this repository entire runner setup --yes # Create the generic defaults and stop entire runner setup --defaults-only # Print the tailoring prompt for your own agent entire runner setup --print-prompt # Preview the tailoring for the risk runner without writing entire runner setup risk --dry-run --sources repo ``` > [!WARNING] > > `--yes` rewrites files in `.entire/runners/`. Review changes with `git diff -- .entire/runners/` before committing. ## Continue With > **[review](/cli-reference/review)** > > Run a multi-agent review against a branch. > **[Glossary](/glossary#runner)** > > See how runners and trails fit together. # search Source: https://docs.entire.com/cli-reference/search Search checkpoints, commits, and sessions with hybrid semantic and keyword matching, or search code content with --code. Search indexed Entire history from the CLI. Add `--code` to search code content instead. ```bash theme={null} entire search [QUERY] [flags] ``` `entire checkpoint search` is an equivalent alias. In CLI versions 0.9.0 and earlier, `entire search` was hidden from `entire --help` but remained runnable. By default, search is scoped to the current repository. Use `--repo`, `--all-repos`, or `repo:*` to change the scope. Run without arguments to open interactive search. Use `--json` for machine-readable output. > [!NOTE] > > **Requires a published repository.** Entire answers this from its own servers rather than from your local clone, so the repository must be published somewhere Entire can reach and its checkpoints pushed. > > Publish by [creating a repository on Entire](/guides/repositories/repository) or by [mirroring a GitHub repository](/guides/repositories/mirrors), then `git push`. `entire enable` does not create or push to a remote for you. > > Your work becomes available shortly after it reaches Entire, so give a recent push a couple of minutes before treating a missing result as a problem. Search queries Entire's index, so indexing has to finish before new work appears. See [What Is Indexed and When](/guides/search/what-is-indexed). ## Examples ```bash theme={null} entire search "auth token refresh" entire search "auth token refresh" --repo entireio/cli entire search "repo:* auth token refresh" entire search "retry logic" author:alex branch:main date:month entire search "auth token refresh" --json entire search "auth token refresh" --compact --limit 5 ``` ## Flags | Flag | Description | | - | - | | `--all-repos` | Search all accessible repositories instead of only the current repository. | | `--author NAME` | Filter by author name. | | `--branch NAME` | Filter by branch name. | | `--case-sensitive` | Reserved for future case-sensitive code search. Only valid with `--code`; currently does not change backend matching. | | `--code` | Search code content across repositories instead of checkpoints, commits, and sessions. | | `--compact` | Return trimmed JSON for agents. Implies `--json` and cannot be combined with `--code`. | | `--date PERIOD` | Filter by time period. Use `week` or `month`. | | `--json` | Output as JSON. | | `--limit N` | Maximum number of results per page, or total results with `--code`. Default is `10`. | | `--page N` | Page number, 1-based. Default is `1`. | | `--repo REPOSITORY` | Filter by repository. Accepts `gh/owner/repo`, `et/project/repo`, `owner/repo`, a repository ULID, or `*`; repeatable and comma-separated. | ## Inline Filters CLI queries also support inline filters: ```bash theme={null} entire search "retry logic author:alex date:month branch:main repo:entireio/cli" ``` Supported inline filters are: * `author:NAME` * `date:week|month` * `branch:NAME` * `repo:OWNER/NAME` * `repo:*` ## Compact Output for Agents Use `--compact` to omit full prompts and return a smaller semantic-search response: ```bash theme={null} entire search "auth token refresh" --compact --limit 5 ``` Each result includes its identifiers, type, ranking metadata, and a truncated title. Repository, branch, author, date, files touched, and match snippets appear when available. `--compact` implies `--json`. It cannot be combined with `--code`. For semantic search, `--limit` sets the maximum results per page. For Code Search, it sets the maximum total results. ## Code Search Use `--code` to search code content instead of checkpoints, commits, and sessions. Results are grouped under a `repo:path` heading with line-numbered matches beneath it. ```bash theme={null} entire search --code "refreshAccessToken" entire search --code "refreshAccessToken" --repo entireio/cli entire search --code "repo:* refreshAccessToken" entire search --code "refreshAccessToken" --json ``` Code search matches exact text and is currently case-insensitive. The CLI accepts `--case-sensitive`, but the search backend does not yet apply it. In `--code` mode, `repo:` is the only supported inline filter. The `author:`, `branch:`, and `date:` tokens are treated as literal query text, and the `--author`, `--branch`, `--date`, and `--page` flags do not apply. In interactive search, press `3` to switch to the **Code** tab. The other tabs are **Commits** (`1`) and **Sessions** (`2`). Checkpoint matches fold into their owning sessions. Use `entire checkpoint explain CHECKPOINT_ID` to open a checkpoint directly. ## Continue With > **[Search](/guides/search/overview)** > > Compare semantic and keyword search with literal code search. > **[Search in the CLI](/guides/search/search-in-cli)** > > Use both search modes from your terminal. > **[Search Past Work and Code](/learn/search-past-agent-work)** > > Practice search with a guided tutorial. > **[What Is Indexed and When](/guides/search/what-is-indexed)** > > Check availability, timing, and repository scope. # session Source: https://docs.entire.com/cli-reference/session View and manage agent sessions tracked by Entire. View and manage agent sessions tracked by Entire. ```bash theme={null} entire session SUBCOMMAND ``` `entire session` is also available as `entire sessions`. ## Session Lifecycle ```mermaid theme={null} flowchart LR start["Agent starts"] --> active["Active"] active -->|"tracking lingers after the agent exits"| stale["Stale"] active -->|"session stop"| stopped["Stopped"] stale -->|"session stop --force"| stopped stopped -->|"session resume"| resumed["Resumed"] resumed -->|"start agent"| active elsewhere["Active in another worktree"] -->|"session adopt"| adopted["Adopted"] adopted --> active transcript["Existing transcript"] -->|"session attach"| attached["Attached"] attached --> checkpoint["Checkpoint linked to latest commit"] history["Past local transcript"] -->|"entire import"| imported["Imported"] imported --> archive["Checkpoint for inspection only"] ``` The diagram shows the paths through a session workflow. `entire session info` reports live sessions as active or ended. Stale, resumed, adopted, attached, and imported describe a session's condition or how its context entered Entire: | State or Outcome | Meaning | | - | - | | Active | Entire is tracking the agent session. | | Stale | The agent has stopped, but its tracking state still appears active. Stop it to clear the live state. | | Stopped | `entire session stop` marked the session as ended. | | Resumed | `entire session resume` checked out the branch and restored the session log. Starting the agent returns the session to active work. | | Adopted | `entire session adopt` moved an active session from another worktree into the current repository. | | Attached | `entire session attach` linked an existing transcript to the latest commit and checkpoint. | | Imported | `entire import` stored past transcript history as a checkpoint for inspection only, with no commit link. | ## session current Show the session running this command, or the most recent one in this worktree. When an agent runs this command, Entire reports that agent's own session, read from the session ID the agent publishes into the environment of the commands it runs. Failing that, it falls back to the most recently active session in this worktree, and then to the most recent one anywhere in the repository's shared session store. The output says which one you got: the `Resolved` line in text mode, or the `resolution` field with `--json`. Only `caller-env` and `ancestry` identify the session running the command; `other-worktree` can be any unrelated session, because every worktree of a repository shares one store. Check it before acting on the session. ```bash theme={null} entire session current [flags] ``` | Flag | Description | | - | - | | `--json` | Output as JSON | | `--transcript` | Stream raw agent transcript bytes to stdout | ## session list List all sessions tracked by Entire, including ended sessions. ```bash theme={null} entire session list [flags] ``` For active sessions only, use [`entire status`](/cli-reference/status). | Flag | Description | | - | - | | `--json` | Output as JSON | ## session info Show detailed information for a specific session. `entire session info` shows agent, model, status, worktree, timing, token usage, checkpoint linkage, and files touched. ```bash theme={null} entire session info SESSION_ID [flags] ``` | Flag | Description | | - | - | | `--json` | Output as JSON | | `--transcript` | Stream raw agent transcript bytes to stdout | ## session tokens Show token usage and optimization recommendations for a session. ```bash theme={null} entire session tokens [SESSION_ID] [flags] ``` When you omit the session ID, Entire identifies the calling agent's session from agent session IDs and process ancestry, falling back to the most recently active session in this worktree and then elsewhere in the repository. The report says how the session was resolved, and ambiguous or cross-worktree matches also print a warning on standard error. | Flag | Description | | - | - | | `--agent-brief` | Give agents compact guidance for the next step | | `--current` | Prefer the current worktree's most recent session | | `--json` | Output as JSON | ## session stop Stop one or more active sessions. ```bash theme={null} entire session stop [SESSION_ID] [flags] ``` | Flag | Description | | - | - | | `--all` | Stop all active sessions | | `-f, --force` | Skip the confirmation prompt | `entire session stop` marks sessions as ended. It does not create a checkpoint or flush pending work. Commit first when you want Entire to link session context to code changes. ```bash theme={null} # Stop a specific session without confirmation entire session stop SESSION_ID --force # Stop all active sessions without confirmation entire session stop --all --force ``` ## session attach Attach an existing agent session that Entire did not capture automatically. ```bash theme={null} entire session attach SESSION_ID [flags] ``` This command reads the session transcript, creates or updates a checkpoint, and links it to the latest commit. Use it if you started the session before installing hooks, the hooks did not fire, or you want to preserve a research session. If the latest commit already has an `Entire-Checkpoint` trailer, Entire adds the session to that checkpoint. Otherwise, Entire creates a checkpoint and offers to amend the commit with the trailer. | Flag | Description | | - | - | | `-a, --agent NAME` | Agent that created the session. Defaults to `claude-code`. Run `entire agent list` to see registered agents, including discovered [agent integrations](/agents/agent-integration-protocol/overview). | | `-f, --force` | Skip confirmation and amend the latest commit with the checkpoint trailer | | `--review` | Tag the attached session as an agent review | | `--skills SKILL` | Declare a review Skill that ran. Repeat the flag for multiple Skills. Only used with `--review`. | ```bash theme={null} # Attach a Codex session and amend HEAD automatically entire session attach SESSION_ID --agent codex --force # Attach a session as a review entire session attach SESSION_ID --agent codex --review # Record multiple Skills used during a review entire session attach SESSION_ID --review --skills review --skills security ``` > [!NOTE] > > `entire session attach` requires at least one commit in the repository. If Entire cannot locate the transcript for the selected agent, it tries to detect the agent from known transcript locations. ## session adopt Adopt an active session from another worktree into the current repository. ```bash theme={null} entire session adopt [SESSION_ID] --from SOURCE_WORKTREE [flags] ``` Use this command when an agent starts in one repository or worktree, then moves and makes changes in another. | Flag | Description | | - | - | | `--from PATH` | Source worktree that already tracks the session | | `--force` | Replace an existing local state file for the same session | | `--yes` | Confirm adoption and replacement within the same store without prompting | ## session resume Resume an agent session from a branch or interactive picker. ```bash theme={null} entire session resume [BRANCH] [flags] ``` With no argument, Entire opens an interactive picker of stopped sessions across all worktrees. After you select a session, Entire checks out its branch, restores the session log, and asks whether to start the agent. With a branch argument, Entire: 1. Checks out the specified branch. 2. Finds the session ID from commits unique to the branch. 3. Restores the session log if it does not exist locally. 4. Asks whether to start the agent in an interactive terminal or prints the resume command in a terminal without interactive input. | Argument | Description | | - | - | | `BRANCH` | Optional branch that contains the session to resume | | Flag | Description | | - | - | | `-f, --force` | Resume from an older checkpoint without confirmation and overwrite the local session log from that checkpoint | ```bash theme={null} # Select a stopped session interactively entire session resume # Resume the session associated with a branch entire session resume BRANCH # Resume from an older checkpoint without confirmation entire session resume BRANCH --force ``` > [!NOTE] > > If the branch exists on the remote but not locally, Entire prompts you to fetch it. > [!WARNING] > > If the branch contains newer commits without checkpoints, Entire can reset Git state to the most recent commit with a checkpoint. Entire prompts before continuing unless you use `--force`. # status Source: https://docs.entire.com/cli-reference/status Show the current Entire status for this repository. Show whether Entire is currently enabled or disabled for this repository. ```bash theme={null} entire status [flags] ``` | Flag | Description | | - | - | | `--detailed` | Show detailed status for each settings file | | `--json` | Output as JSON | For all sessions, including ended ones, use [`entire session list`](/cli-reference/session#session-list). # tokens Source: https://docs.entire.com/cli-reference/tokens Analyze token usage across sessions and checkpoints. Analyze token usage across sessions and checkpoints. ```bash theme={null} entire tokens SUBCOMMAND ``` `entire tokens` is experimental and appears under [labs](/cli-reference/labs) while the workflow is still being refined. Three commands report on token usage, at different scopes: | Command | Scope | | - | - | | [`entire session tokens`](/cli-reference/session#session-tokens) | One session | | [`entire checkpoint tokens`](/cli-reference/checkpoint#checkpoint-tokens) | One checkpoint | | `entire tokens profile` | Committed checkpoint history | ## tokens profile Aggregate token usage and recommendations across committed checkpoint history. ```bash theme={null} entire tokens profile [flags] ``` | Flag | Description | | - | - | | `--all` | Analyze all committed checkpoints. | | `--json` | Output as JSON. | | `--limit N` | Maximum committed checkpoints to analyze. Defaults to `50`. | ```bash theme={null} entire tokens profile entire tokens profile --all entire tokens profile --limit 200 --json ``` The profile reads committed checkpoint metadata only. It does not inspect transcripts or source files, so it is deterministic and adds no token cost while you diagnose token usage. By default it scans the latest 50 committed checkpoints. ## Continue With > **[session tokens](/cli-reference/session#session-tokens)** > > Token usage and recommendations for one session. > **[checkpoint tokens](/cli-reference/checkpoint#checkpoint-tokens)** > > Token usage and recommendations for one checkpoint. # trail Source: https://docs.entire.com/cli-reference/trail Create, review, and merge trails across repositories and branches. Manage [trails](/glossary#trail): project intent, the repository branches linked to it, discussions, findings, approvals, and merges. ```bash theme={null} entire trail SUBCOMMAND [flags] ``` `entire trail` may not appear in `entire help`; run `entire trail --help` to see its subcommands. Coding agents can run `entire agent-help trail` for the same surface with agent-specific guidance. Trail commands call the Entire API with your saved login, so run [`entire login`](/cli-reference/login) first. They need network access and access to the credential store where the login is saved. ## Trails and Changes A project trail holds intent: a title, description, type, priority, assignees, and an open or closed status. It can span several repositories. Each repository branch linked to the trail is a change, and each change is reviewed, approved, and merged on its own. Project trails and changes are numbered separately. Trail numbers are project-wide, so trail `12` means the same trail from any repository in the project. Change numbers are per repository and are written as `/`. Commands that take a `` argument accept these selectors: | Selector | Meaning | | - | - | | `12` | A project trail by its project-wide number. | | A ULID | A project trail by its ID. | | `/` | A change: one repository branch of a trail, such as `app/7`. Accepted by `show`, `checkout`, `resume`, `watch`, `finding`, `approve`, `approvals`, `merge`, and `unlink`. `show` displays the parent trail. | | None | The trail that the current branch belongs to. | Do not pass an entire.com trail URL as a selector. Use the number from the URL instead, and add `--project` when the project is not the current repository's. ## Shared Flags These flags apply to every `entire trail` subcommand. | Flag | Description | | - | - | | `--project PROJECT` | Project as `gh/` or `et/`. Required for `list`. Otherwise defaults to the current repository's namespace: `gh/` for a GitHub mirror, `et/` for a repository hosted on Entire. | | `--repo REPO` | Target repository as `forge/owner/repo`, such as `gh/acme/app`, or a clone URL. Defaults to the `origin` remote. For `list`, it only filters within the required `--project`. Ignored by `resume`. | `--repo` and `--branch` select one repository branch of a trail for `checkout`, `resume`, `finding`, `watch`, `approve`, `approvals`, and `merge`. They do not aggregate across every repository on the trail. ## trail create Create a trail and publish its branch. ```bash theme={null} entire trail create --title TITLE [flags] ``` `create` makes a repository-scoped trail, then links a branch to it. In the current repository it publishes the local branch first, so no separate commit or push is required. It uses the current feature branch, or derives a new branch name from the title when you are on the base branch. Use `--branch` to choose a branch, or `--no-branch` for intent only. With `--no-branch`, the current or `--repo` repository becomes the trail's scope, which requires write access to that repository. `--project` without `--repo` creates unscoped intent instead, which requires project management permission. With `--repo`, no local branch is published. Link existing remote work, or pass `--branch-action create` to create the branch on the server from `--base`. `create` does not commit changes or change your local checkout. Branches are preserved if creation fails. | Flag | Description | | - | - | | `--assignee LOGINS` | Assignee logins. Replaces the complete list; `--assignee=` clears it. | | `--base BRANCH` | Base branch for new code work. Requires `--branch`. | | `--body TEXT` | Trail description. | | `--branch BRANCH` | Branch to use. Defaults to the current feature branch, or a branch derived from the title when on the base branch. | | `--branch-action ACTION` | `link` to link existing remote work, or `create` to create a new branch. Defaults to `link`. Requires `--branch`. | | `--idempotency-key KEY` | Retry key for linking the branch. With intent-only creation, requires project management permission. | | `--json` | Output raw JSON instead of a table. | | `--no-branch` | Create intent only. Cannot be combined with `--branch`, `--base`, or `--branch-action`. | | `--priority PRIORITY` | `urgent`, `high`, `medium`, `low`, or `none`. | | `--status STATUS` | Lifecycle status: `open` or `closed`. | | `--title TITLE` | Trail title. Required. | | `--type TYPE` | `bug`, `feature`, or `task`. | ```bash theme={null} # Create a trail for the current feature branch entire trail create --title "Add rate limiting to the API" --type feature # Create intent only, scoped to this repository entire trail create --title "Investigate flaky login test" --no-branch # Create a trail in another repository and a new branch on the server entire trail create --repo gh/acme/app --title "Fix pagination" \ --branch fix-pagination --branch-action create --base main ``` > [!NOTE] > > With a branch, `--idempotency-key` applies only to the link step. If linking fails after the trail is created, retry with `entire trail link` rather than creating another trail. ## trail list List trails in a project. ```bash theme={null} entire trail list --project PROJECT [flags] ``` `list` shows trails in one project, newest update first, and does not need a checkout. `--project` is required even inside a clone. `--repo` only filters within that project. Omitting `--status` includes every lifecycle state. | Flag | Description | | - | - | | `--json` | Output raw JSON instead of a table. | | `--limit N` | Page size, from 1 to 100. Defaults to `50`. | | `--page-token TOKEN` | Continue from a previous run's `nextPageToken`. Use the same project and filters. | | `--status STATUS` | Filter by `open` or `closed` before pagination. | ```bash theme={null} # List open trails in a GitHub owner's project entire trail list --project gh/acme --status open # List trails in an Entire project that touch one repository entire trail list --project et/platform --repo et/platform/api ``` ## trail show Show trail intent and its repositories and branches. ```bash theme={null} entire trail show [] [flags] ``` Pass a project trail number or ID, or a `/` change to show its parent trail. Without a selector, `show` follows the current branch to its trail. With `--json`, each entry in `changes[]` is one repository branch with its own URL. | Flag | Description | | - | - | | `--branch BRANCH` | Find the trail through this repository branch. Defaults to the current branch when no trail is given. | | `--json` | Output raw JSON instead of a table. | ```bash theme={null} # Show the trail for the current branch entire trail show # Show trail 12 in another project as JSON entire trail show 12 --project gh/acme --json ``` ## trail update Update a trail's intent and lifecycle. ```bash theme={null} entire trail update [] [flags] ``` Without a selector, `update` acts on the current branch's trail. Pass at least one field to change. | Flag | Description | | - | - | | `--add-assignee LOGINS` | Add assignee logins. | | `--assignee LOGINS` | Assignee logins. Replaces the complete list; `--assignee=` clears it. | | `--body TEXT` | Trail description. `--body=` clears it. | | `--branch BRANCH` | Find the trail through this repository branch. Defaults to the current branch when no trail is given. | | `--json` | Output raw JSON instead of a table. | | `--priority PRIORITY` | `urgent`, `high`, `medium`, `low`, or `none`. | | `--remove-assignee LOGINS` | Remove assignee logins. | | `--status STATUS` | Lifecycle status: `open` or `closed`. | | `--title TITLE` | Trail title. | | `--type TYPE` | `bug`, `feature`, or `task`. | ```bash theme={null} # Close the current branch's trail entire trail update --status closed # Raise priority and add an assignee on trail 12 entire trail update 12 --priority high --add-assignee octocat ``` ## trail link Link a repository branch to a trail. ```bash theme={null} entire trail link [flags] ``` `link` attaches an existing remote branch to a project trail, given by number or ID. `--branch` defaults to the current branch. Use `--branch-action create` to create the branch on the server from `--base`. Existing work and reviews are preserved. A branch that already belongs to another trail is rejected. | Flag | Description | | - | - | | `--base BRANCH` | Base branch for new code work. Requires `--branch`. | | `--branch BRANCH` | Branch to link. Defaults to the current branch. Required with `--repo`. | | `--branch-action ACTION` | `link` to link existing remote work, or `create` to create a new branch. Defaults to `link`. | | `--idempotency-key KEY` | Retry key for linking. When omitted, Entire generates one and prints it so a failed link can be retried with the same key. | | `--json` | Output raw JSON instead of a table. | | `--status STATUS` | Lifecycle status for the linked branch: `open` or `closed`. | ```bash theme={null} # Link the current branch to trail 12 entire trail link 12 # Link a branch in another repository to the same trail entire trail link 12 --repo gh/acme/web --branch rate-limit-ui ``` ## trail unlink Unlink a repository branch without deleting its work. ```bash theme={null} entire trail unlink [] [flags] ``` `unlink` removes a repository branch from a trail. The branch, code, reviews, and sessions are preserved. A trail with one open change unlinks it. With several, they are listed so you can pass one as `/` or select it with `--branch`. | Flag | Description | | - | - | | `--branch BRANCH` | Select the repository branch to unlink. | ```bash theme={null} entire trail unlink app/7 ``` ## trail checkout Check out a trail's branch. ```bash theme={null} entire trail checkout [] [flags] ``` The trail can be given as an argument or with `--trail`. Without one, the current branch's trail is used. `--branch` selects the working branch; otherwise the current branch, or the trail's only branch in this repository, is selected. When neither applies, the open changes are listed so you can pass one as `/`. Remote-only branches are fetched. `checkout` must run inside a clone of the trail's repository. The trail is looked up against that clone's `origin` remote, and `--repo` is not accepted. With `--worktree`, the branch is checked out into a Git worktree under `.entire/worktrees` at the repository root instead of switching the current checkout. Gitignored files that match `.worktreeinclude` patterns are copied into the worktree. In a terminal, the command prints a `cd` command for the new worktree. When standard output is not a terminal, it prints only the worktree path. | Flag | Description | | - | - | | `--branch BRANCH` | Select a branch within the trail in this repository. | | `-f, --force` | Skip the prompt before fetching a remote-only branch. | | `--trail TRAIL` | Project trail number, ID, or `/`. Defaults to the current branch's trail. | | `--worktree` | Check out the trail branch in a worktree under `.entire/worktrees` instead of switching this checkout. | ```bash theme={null} # Check out the branch of trail 12 entire trail checkout 12 # Check out a change into its own worktree and enter it cd "$(entire trail checkout app/7 --worktree)" ``` ## trail resume Resume a trail's agent session. ```bash theme={null} entire trail resume [] [flags] ``` The trail can be given as an argument or with `--trail`. Without one, the current branch's trail is used. When several branches match, pass `--branch`. In an interactive terminal, `resume` shows the trail context, restores the checkpoint sessions on the trail branch, and asks whether to start the agent. If the checkpoint has several sessions, you choose which one to start. Non-interactive runs show the same context and print resume commands for the latest checkpoint on the trail branch. Use `--session` or `--checkpoint` to resume an exact session or checkpoint. With a trail number or ID, `--branch` asserts the branch you expect the trail to be attached to. If it does not match, `resume` stops before checking anything out. | Flag | Description | | - | - | | `--branch BRANCH` | Expected trail branch. Fails if the trail is attached to a different branch. | | `--checkpoint ID` | Resume a specific checkpoint on the trail branch. | | `-f, --force` | Skip prompts and overwrite existing session logs from checkpoints. | | `--json` | Output the trail resume context as JSON. | | `--no-resume` | Show the trail resume context without restoring or resuming a session. | | `--session ID` | Resume a specific known local session on the trail branch. | | `--trail TRAIL` | Project trail number, ID, or `/`. Defaults to the current branch's trail. | ```bash theme={null} # Resume the agent session for trail 12 entire trail resume 12 # Show what would be resumed without restoring anything entire trail resume app/7 --no-resume ``` > [!WARNING] > > `--force` overwrites existing local session logs with the versions stored in checkpoints. ## trail watch Tail events for a trail's selected repository branch. ```bash theme={null} entire trail watch [] [flags] ``` `watch` subscribes to the trail's event stream for the selected repository branch and prints events as they arrive. It reconnects automatically when the server caps the connection, about every 50 seconds, and on transient network errors. Without a selector, the current branch's trail is used. | Event | Meaning | | - | - | | `ready` | Initial frame, including the trail and cursor. | | `` | A trail domain event, such as reviews, findings, runners, or monitors. | | `reconnect` | The server cap was reached; the stream is re-established. | | `forbidden` | Access was revoked; the stream ends. | | `error` | A server-side error; treated as a reconnect. | | Flag | Description | | - | - | | `--branch BRANCH` | Select a repository branch within the trail. | | `--json` | Print each event as a single JSON line. | | `--once` | Open one connection, then exit instead of reconnecting. | | `--show-pings` | Print keepalive pings, which are otherwise suppressed. | ```bash theme={null} # Follow events for the current branch's trail as JSON lines entire trail watch --json ``` ## trail comment Discuss the whole trail across repositories. ```bash theme={null} entire trail comment SUBCOMMAND [flags] ``` Comments are discussions between people on the whole trail. Agents report through [findings](#trail-finding) instead: when Entire detects an agent session, the write subcommands (`add`, `reply`, `edit`, `delete`, `resolve`, `unresolve`) are refused, while `list` and `show` still work. These flags apply to every `trail comment` subcommand: | Flag | Description | | - | - | | `--branch BRANCH` | Find the trail through this repository branch. | | `--trail TRAIL` | Project trail number, ID, or `/`. Defaults to the current branch's trail. | Every subcommand also accepts `--json` to output raw JSON instead of a table. ### trail comment list List the trail's discussions. ```bash theme={null} entire trail comment list [flags] ``` ### trail comment show Show a discussion and its messages. ```bash theme={null} entire trail comment show [flags] ``` ### trail comment add Start a discussion on the trail. ```bash theme={null} entire trail comment add -m BODY [flags] ``` | Flag | Description | | - | - | | `-m, --body TEXT` | Message body. Required. | | `--title TITLE` | Discussion title. | ### trail comment reply Reply to a discussion. ```bash theme={null} entire trail comment reply -m BODY [flags] ``` | Flag | Description | | - | - | | `-m, --body TEXT` | Message body. Required. | ### trail comment edit Edit a discussion message. ```bash theme={null} entire trail comment edit -m BODY [flags] ``` | Flag | Description | | - | - | | `-m, --body TEXT` | New message body. Required. | ### trail comment delete Delete a discussion message. ```bash theme={null} entire trail comment delete [flags] ``` | Flag | Description | | - | - | | `-f, --force` | Confirm the deletion. | ### trail comment resolve Resolve a discussion. ```bash theme={null} entire trail comment resolve [flags] ``` ### trail comment unresolve Reopen a resolved discussion. ```bash theme={null} entire trail comment unresolve [flags] ``` ```bash theme={null} # Start a discussion on trail 12 entire trail comment add --trail 12 --title "Rollout plan" -m "Ship behind a flag first?" # Reply, then resolve entire trail comment reply DISCUSSION_ID -m "Agreed, flag it." entire trail comment resolve DISCUSSION_ID ``` ## trail approve Approve a trail's selected repository branch. ```bash theme={null} entire trail approve [] [flags] ``` Without a selector, the current branch's trail is used. Only the selected branch is approved, not every repository on the trail. The branch must be open. | Flag | Description | | - | - | | `--branch BRANCH` | Select a repository branch within the trail. | | `-m, --message TEXT` | Optional approval comment. | ```bash theme={null} entire trail approve app/7 -m "Looks good" ``` ## trail approvals List approval decisions on a trail's selected repository branch. ```bash theme={null} entire trail approvals [] [flags] ``` | Flag | Description | | - | - | | `--branch BRANCH` | Select a repository branch within the trail. | | `--json` | Output as JSON. | ## trail merge Merge one of a trail's changes into its base branch. ```bash theme={null} entire trail merge [] [flags] ``` Without a selector, `merge` merges the current branch's change. A trail with one open change merges it, in any repository. With several, they are listed with their review state so you can pass one as `/` or select it with `--branch` and `--repo`. Each change merges on its own; merging one never merges the trail's other changes. The trail's [gates](/guides/trails/gates) are checked first: approvals, CI checks, the base branch's CI, being up to date, and any other configured gates. When a blocking gate fails or is still pending, the blocking gates are listed and nothing is merged. A change that conflicts with its base is never merged; resolve the conflicts first. `--dry-run` only reports whether the change can be merged. It exits non-zero when the merge would be refused, so it can gate CI. After merging a change in a repository hosted on Entire, the server deletes the trail's branch when the repository's delete-branch-on-merge setting is on. Your local branch is not touched. `--delete-branch` and `--no-delete-branch` override that setting for one merge. Before deleting the branch, the server moves any open trails based on it onto this trail's base, and keeps the branch when one of them cannot be moved. A GitHub-backed trail's branch follows GitHub's own auto-delete setting, so both flags are refused there. | Flag | Description | | - | - | | `--branch BRANCH` | Select a repository branch within the trail. | | `--delete-branch` | Delete the trail's branch after merging, overriding the repository setting. Repositories hosted on Entire only. | | `--dry-run` | Only check whether the change can be merged; do not merge. | | `--force` | Merge even when blocking gates fail. Requires bypass permission. | | `--json` | Output as JSON. | | `--no-delete-branch` | Keep the trail's branch after merging, overriding the repository setting. Repositories hosted on Entire only. | | `-y, --yes` | Skip the confirmation prompt before `--force` bypasses gates. | ```bash theme={null} # Check whether the current branch's change can merge entire trail merge --dry-run # Merge one change of trail 12 entire trail merge app/7 ``` > [!WARNING] > > `--force` bypasses blocking gates and is recorded on the trail. The repository's bypass policy decides who may use it. Without a terminal to confirm in, or with `--json`, `--force` also requires `--yes`. ## trail finding Manage a trail's agent findings. ```bash theme={null} entire trail finding [] [flags] entire trail finding SUBCOMMAND [flags] ``` A [finding](/glossary#finding) is an issue raised against a trail's branch, typically by a [runner](/cli-reference/runner) or an agent review. Findings apply only to the selected repository branch, not the whole trail. Run `entire trail finding` with no subcommand to show the finding dashboard for the current branch's trail; it takes the same filter flags as [`trail finding list`](#trail-finding-list). These flags apply to every `trail finding` subcommand: | Flag | Description | | - | - | | `--branch BRANCH` | Select a repository branch within the trail. | | `--trail TRAIL` | Project trail number, ID, or `/`. Defaults to the current branch's trail. Pass the trail either positionally or with `--trail`, not both. | ### trail finding list List findings for a trail. ```bash theme={null} entire trail finding list [] [flags] ``` By default, `list` shows open findings on the current code version. | Flag | Description | | - | - | | `--cursor CURSOR` | Continue from the next cursor returned by a previous page. | | `--freshness FRESHNESS` | Filter by code-version freshness: `current`, `stale`, or `any`. Defaults to `current`. | | `--include-dismissed` | Include dismissed findings. | | `--json` | Output as JSON. | | `-n, --limit N` | Maximum number of findings to show. Defaults to `100`. | | `--severity SEVERITY` | Filter by comma-separated severity values: `high`, `medium`, `low`. | | `--status STATUS` | Filter by comma-separated lifecycle status: `open`, `resolved`, `dismissed`, or `any` for all. Defaults to `open`. | ### trail finding show Show a finding. ```bash theme={null} entire trail finding show [] ``` ### trail finding add Create a finding on a trail. ```bash theme={null} entire trail finding add [] -m BODY [flags] ``` A finding can carry a location and a suggested change. A patch must modify a single existing file in this worktree; when `--file` is omitted, the location defaults to the file the patch modifies. | Flag | Description | | - | - | | `-m, --body TEXT` | Finding body. Required. | | `--client-id KEY` | Retry key for this finding and its review. The server keeps it for 24 hours; reuse it with the same fields. | | `--confidence N` | Finding confidence from `0.0` to `1.0`. | | `--end-line N` | End line for the finding location. Requires `--line` or `--start-line`. | | `--file PATH` | File path for the finding location. Required with any line flag. | | `--instruction TEXT` | Manual suggested-change instruction to attach. | | `--json` | Output as JSON. | | `--line N` | Line number for the finding location. Cannot be combined with `--start-line`. | | `--patch DIFF` | Unified-diff suggested change to attach. | | `--patch-file PATH` | Read the unified-diff suggested change from a file, or `-` for standard input. Cannot be combined with `--patch`. | | `--severity SEVERITY` | `high`, `medium`, or `low`. | | `--start-line N` | Start line for the finding location. | ### trail finding apply Apply a finding's unified-diff suggestion to the current worktree. ```bash theme={null} entire trail finding apply [] [flags] ``` By default, `apply` only changes files. Pass `--resolve` to also mark the finding resolved once the patch applies. `apply` patches this clone, so `--repo` is not accepted. | Flag | Description | | - | - | | `--check` | Only check whether the patch applies; do not modify files. | | `--resolve` | Mark the finding resolved after applying. | ### trail finding resolve Resolve a finding. ```bash theme={null} entire trail finding resolve [] [flags] ``` | Flag | Description | | - | - | | `-m, --message TEXT` | Status reason to record. | ### trail finding dismiss Dismiss a finding. ```bash theme={null} entire trail finding dismiss [] [flags] ``` | Flag | Description | | - | - | | `-m, --message TEXT` | Status reason to record. | ### trail finding reopen Reopen a resolved or dismissed finding. ```bash theme={null} entire trail finding reopen [] [flags] ``` | Flag | Description | | - | - | | `-m, --message TEXT` | Status reason to record. | ### trail finding update Update a finding's metadata. Pass at least one of `--body`, `--severity`, or `--confidence`. ```bash theme={null} entire trail finding update [] [flags] ``` | Flag | Description | | - | - | | `-m, --body TEXT` | Finding body. | | `--confidence N` | Finding confidence from `0.0` to `1.0`. | | `--json` | Output as JSON. | | `--severity SEVERITY` | `high`, `medium`, or `low`. | ```bash theme={null} # List open high-severity findings for the current branch entire trail finding list --severity high # Include stale and resolved findings entire trail finding list --freshness any --status any # Add a finding with a location entire trail finding add -m "Missing nil check on the response" \ --severity medium --file internal/api/client.go --line 42 # Check, then apply a suggested change and resolve the finding entire trail finding apply FINDING_ID --check entire trail finding apply FINDING_ID --resolve # Dismiss a finding with a reason entire trail finding dismiss FINDING_ID -m "Intended behavior; covered by tests" ``` > [!NOTE] > > When the findings gate is configured, open findings at or above its severity threshold block the merge until each one is resolved or dismissed. See [Gates](/guides/trails/gates). ## Continue With > **[Trails overview](/guides/trails/overview)** > > Learn how trails group intent, branches, and checkpoints. > **[Agents](/guides/trails/agents)** > > Configure the automated evaluations that run on a trail. > **[Gates](/guides/trails/gates)** > > Configure the checks a change must pass before it merges. > **[runner](/cli-reference/runner)** > > Set up the runners that raise findings on a trail. # version Source: https://docs.entire.com/cli-reference/version Show build information including the CLI version, Go version, and OS/architecture. Show build information including the CLI version, Go version, and OS/architecture. ```bash theme={null} entire version ``` You can also use the `--version` flag on the root command: ```bash theme={null} entire --version ``` Both produce the same three lines: the CLI version, the Go version the release was built with, and your platform. See [Verify the Install](/installation#verify-the-installation) for a worked example. > [!NOTE] > > Nightly and development builds report a longer version string that encodes the build date and commit. Include the whole line when you file a bug report. # why Source: https://docs.entire.com/cli-reference/why Explain the commit, checkpoint, prompt, and session behind a file or line. Explain the captured context behind a file or line. ```bash theme={null} entire why FILE[:LINE] [flags] ``` Use `entire why` when you want to jump from a file or specific line to the commit, checkpoint, prompt, and session behind it. ## Flags | Flag | Description | | - | - | | `--line LINE` | Explain a specific line, for example `12`. This is the same as `FILE:12`. | | `--json` | Output explanation as JSON | ## Examples ```bash theme={null} entire why overview.mdx entire why overview.mdx:12 entire why overview.mdx --line 12 entire why overview.mdx:12 --json ``` ## Continue With > **[Investigate Why Code Exists](/learn/investigate-why-code-exists)** > > Use `entire why` in a full provenance investigation. > **[checkpoint explain](/cli-reference/checkpoint#checkpoint-explain)** > > Inspect the full checkpoint context. # Delete Your Account Source: https://docs.entire.com/delete-account Permanently delete your Entire account, and cancel during the 7-day cooldown You can permanently delete your Entire account from [entire.com](https://entire.com) at any time. This page covers what gets deleted, the 7-day cooldown, how to cancel, and what happens when deletion completes. This is how you exercise your **right to erasure** (the "right to be forgotten") under the GDPR and similar laws. For what data we hold and how long we keep it, see the [Privacy Policy](https://entire.com/privacy). ## Before You Start When you open the delete dialog, Entire shows you a preview of exactly what will happen to your account. Review it before you confirm. * **Permanently deleted**: your Entire account, your profile data, and the repositories connected to your personal account. * **Access you'll lose**: your memberships in other organizations and any roles granted to you. You are removed from those organizations; the organizations themselves and their repositories are not deleted. Your Git repositories are not touched. Checkpoint data lives in your own repository, either as one Git ref per checkpoint under `refs/entire/checkpoints/` or on the `entire/checkpoints/v1` branch, so deleting your Entire account does not erase it. Delete those refs yourself if you want the transcripts gone. See [Where your data lives](/security#where-your-data-lives). > [!WARNING] > > You can't delete your account while you **own an organization**. Transfer > ownership or delete each organization you own first, then delete your account. > The dialog lists the organizations you still own. ## Delete Your Account **1. Open Account Settings** Sign in to [entire.com](https://entire.com), open your **Account** settings, and find the **Danger zone**. **2. Start the Deletion** Click **Delete account**. Entire loads a preview of what will be deleted and which access you'll lose. **3. Confirm** Type your GitHub username to confirm, then click **Delete my account**. If you still own an organization, resolve the blockers listed in the dialog first. **4. You're Signed Out** Your account is scheduled for deletion and you're signed out everywhere immediately. A 7-day cooldown begins. ## 7-Day Cooldown Deletion is not immediate. Your account enters a **7-day cooldown** during which nothing is erased yet and you can still change your mind. While the cooldown is running: * You're signed out, and your access tokens stop working, so you can't push new work or use the API. * You can sign back in to cancel. Signing in **does not** cancel the deletion on its own. You have to click **Cancel deletion**. ### Cancel a Pending Deletion **1. Sign Back In** Return to [entire.com](https://entire.com) and sign in. You'll see a banner: *"Your account is scheduled for deletion on \[date]."* **2. Cancel** Click **Cancel deletion**. Your account is no longer scheduled for deletion and full access is restored right away. > [!WARNING] > > Once the 7-day cooldown ends, deletion is **permanent and cannot be undone**. > Erased data cannot be recovered. ## What Happens When Deletion Completes When the cooldown ends, Entire permanently erases your account and personal data across every region where we store it. We also ask the third-party services we use, such as our analytics and CRM providers, to erase your personal data. Those providers are listed on our [Subprocessors](https://entire.com/subprocessors) page. ## What We Keep After Deletion We keep a small amount of information after deletion where the law requires it: tax, accounting, and security records. The [Privacy Policy](https://entire.com/privacy) lists what and for how long. Repository content follows the repository, not your account: it is retained for as long as the repository exists on our services and is deleted when the repository (or the relevant history) is deleted. ## Other Data Requests Deleting your account is the fastest way to erase your personal data yourself. To ask for a copy of your data, correct it, or move it somewhere else, email us. > **[Email legal@entire.io](mailto:legal@entire.io)** > > Reach us for privacy questions and requests about your data. The [Privacy > Policy](https://entire.com/privacy) lists your rights in full. # Frequently Asked Questions Source: https://docs.entire.com/faq Answers to common questions about checkpoints and attribution. ## Checkpoints ### Why Does Entire Use Commit Trailers Instead of Git Notes? Entire links commits to checkpoints with an `Entire-Checkpoint` trailer: ```text theme={null} Entire-Checkpoint: a3b2c4d5e6f7 ``` The trailer points to checkpoint metadata stored in your repository: one Git ref per checkpoint under `refs/entire/checkpoints/` by default, or the shared `entire/checkpoints/v1` branch in repositories that use the legacy branch backend. Entire uses this approach because commit trailers survive common Git workflows better than metadata attached only to a commit SHA. Git notes have a few practical limitations: * Normal Git pushes skip them unless you configure note refs separately * They attach to commit SHAs, which change during rebases, amends, and cherry-picks * Hosted Git platforms do not consistently support them in review and merge workflows By storing the stable checkpoint ID in the commit message, Entire keeps the link with the commit itself. That is more reliable for teams that rebase, amend, cherry-pick, use hosted merge flows, or have contributors using different Git clients. ## Attribution ### What Do `entire blame` and `entire why` Actually Tell Me? Both commands answer questions about a line of code, and both answer them at the level of the commit that introduced the line, not the line itself. [`entire blame`](/cli-reference/blame) shows git-blame-style output with the attribution status of each line's introducing commit: * `AI`: Entire attributed the commit to an AI agent session * `MX`: the commit mixed AI-attributed and human-attributed work * `HU`: the commit carries no AI-attributed checkpoint data * `??`: the line is uncommitted [`entire why`](/cli-reference/why) takes a line and returns the commit, checkpoint, prompt, and session behind it. What they promise: * The commit that introduced the line as Git currently records it * Whether that commit carried agent-attributed checkpoint data * The session and prompt behind that commit, when a checkpoint is linked What they do not promise: * That a given line was written by a specific agent or person. The tag describes the whole commit, so a line hand-edited inside an `AI` commit still reads as `AI`. * That the answer survives history rewriting. Both commands follow Git blame, so a rebase, squash, or manual conflict resolution reattributes the line to whichever commit Git now credits. * Line-level counts. `--long` adds agent, model, author, and session columns, all still commit-level. > [!NOTE] > > `entire blame` and `entire why` are [labs commands](/cli-reference/labs). They work today, and their output may change. ### Why Doesn't Entire Provide Durable Line-Level AI Attribution? Entire preserves durable session and commit provenance. That means Entire can reliably answer questions like: * Which session produced this commit? * Which prompts and transcript led to this change? * Which checkpoint is linked to this commit? Entire can calculate attribution for a session or commit, such as how many changed lines came from an agent versus a human. That is different from assigning a permanent owner to every line of code as it moves through Git history. Durable line-level attribution is much harder. In normal team workflows, line-level metadata becomes fragile when: * Commits are rebased, amended, cherry-picked, or squashed * Merge conflicts are resolved manually * Merges happen in hosted Git UIs * Human edits are mixed into a manual commit before commit time The core issue is that lines move. A line can shift, split, merge with nearby edits, or be rewritten later. Keeping per-line attribution correct across those changes requires repair logic that runs everywhere history changes. Entire currently prioritizes a more durable record: * Preserve the full session transcript * Link commits to stable checkpoint IDs * Keep commit-level provenance intact across common Git workflows ## Continue With > **[Investigate Why Code Exists](/learn/investigate-why-code-exists)** > > Trace a surprising line from attribution to the checkpoint context behind it. > **[Glossary](/glossary)** > > Definitions for checkpoints, sessions, trails, runners, and the rest of Entire's vocabulary. # Glossary Source: https://docs.entire.com/glossary The vocabulary Entire uses across the CLI, the web interface, and this documentation. 38 terms | Glossary term | Definition | | - | - | | **Agent** | An AI coding assistant connected to Entire, such as [Antigravity CLI](/agents/antigravity), [Claude Code](/agents/claude-code), [Codex](/agents/codex), [Copilot CLI](/agents/copilot-cli), [Cursor](/agents/cursor), [Factory](/agents/factory-droid), [OpenCode](/agents/opencode), or [Pi](/agents/pi). | | **Agent run** | One execution of an agent inside a session. Entire compares your work before each run with the agent's changes so line attribution can stay accurate. | | **Checkpoint** | A save point for your work. Entire creates checkpoints around agent activity and links committed ones to Git commits. | | **Checkpoint ID** | The identifier for a checkpoint, shown in the CLI and entire.com. The format follows the [storage backend](#checkpoint-storage-backend): ref-based storage, the default, uses a 26-character time-sortable ULID such as `01KVBJCWYA4YW6J5M9GP655HZN`; branch-based storage uses 12 hexadecimal characters such as `8a513f56ed70`. | | **Checkpoint linking** | The connection between a Git commit and the Entire checkpoint that captured the session context behind it. | | **Checkpoint ref** | The Git ref that holds one checkpoint under the ref-based backend, at `refs/entire/checkpoints//`. List them with `git for-each-ref refs/entire/checkpoints/`. | | **Checkpoint remote** | A Git remote that holds checkpoint metadata separately from your code remote. By default, Entire pushes checkpoint metadata to your code remote. | | **Checkpoint storage backend** | How Git organizes checkpoints in your repository. `git-refs` writes one [checkpoint ref](#checkpoint-ref) per checkpoint and is the default for repositories enabled with CLI 0.10.0 or later. `git-branch` writes all of them to the [checkpoints branch](#checkpoints-branch). See [Session Storage](/guides/checkpoints/checkpoint-storage). | | **Checkpoints branch** | The Git branch where Entire stores checkpoint and session metadata under the branch-based backend. Entire names the branch `entire/checkpoints/v1`. | | **Code Search** | A literal search over the text of tracked files on a repository's indexed branch, returning the files and lines that contain a match. Run `entire search --code`, or open the **Code** tab in entire.com. | | **Commit trailer** | Structured metadata that Entire appends to a Git commit message, such as `Entire-Checkpoint` and `Entire-Attribution`. | | **Committed checkpoint** | A checkpoint that Entire has linked to a Git commit and written to checkpoint storage. | | **Dispatch** | A markdown summary of recent agent work across one or more repositories, branches, and time windows. | | **Entire CLI** | The command line tool that records sessions, creates checkpoints, links commits, and syncs metadata. | | **entire.com** | The web interface for searching and browsing repositories, sessions, checkpoints, dispatches, and agent activity captured by Entire. | | **Entire Repository** | A Git repository that EntireDB serves. Entire can host the repository or connect it to an upstream GitHub repository through one or more mirror placements. | | **Entire-Attribution** | A commit trailer that records how much of a commit came from the agent versus a human. | | **Entire-Checkpoint** | A commit trailer that records the checkpoint ID associated with a commit. | | **Finding** | A single issue a review [runner](/glossary#runner) raises against a branch or [trail](/glossary#trail), such as a bug, a regression, or a missing test. Open findings block the trail from merging until you resolve or dismiss each one. | | **Line attribution** | Entire's calculation of how many changed lines in a commit came from the agent and how many came from a human. | | **Metadata** | Structured data Entire records about sessions and checkpoints, including timestamps, agent type, token usage, attribution, and configuration. | | **Mirror** | A connection between a GitHub repository and Entire. GitHub remains the upstream repository, while Entire serves Git traffic through one or more regional mirror placements. | | **Mirror placement** | A copy of a GitHub-backed repository on one EntireDB cluster. Each placement has its own cluster, status, and `entire://` URL. | | **Nested session** | A child session created when an agent spawns another agent or sub-agent during the same body of work. | | **Plugin** | An executable named `entire-` on your `$PATH` that adds a command to the Entire CLI. Running `entire ` dispatches to it. Distinct from a [skill](/glossary#skill), which teaches an agent to use Entire in natural language. | | **Repository object** | The control-plane record that identifies an Entire Repository and stores metadata such as its owning project, visibility, and placement information. The `entire repo` commands manage these objects. | | **Runner** | A config-driven job that runs an AI coding agent in an isolated cloud sandbox against a branch or [trail](/glossary#trail). You define runners per repository in `.entire/runners/`. They produce Entire's automated review signals, including review comments, summaries, and scores for risk, drift, confidence, and security. | | **Search** | Entire's search over every indexed repository you can access, covering both [semantic search](#semantic-search) and [Code Search](#code-search) so one query returns the code and the work behind it. See the [Search overview](/guides/search/overview). | | **Semantic search** | A search over indexed Entire history that matches by phrase, meaning, or agent context rather than by exact words, returning related commits and sessions. Its literal counterpart is [Code Search](#code-search). | | **Session** | A complete interaction with an AI coding agent from start to finish. Sessions include prompts, responses, code changes, checkpoints, token usage, metadata, and line attribution. | | **Session branch** | A Git branch that holds captured session data without adding commits to your working branch. | | **Session context** | The prompts, responses, tool activity, code changes, and metadata that explain what happened during a session. | | **Shadow branch** | A temporary local branch that holds checkpoints during active sessions. Entire names shadow branches like `entire/-` and does not push them to remote repositories. | | **Skill** | A reusable workflow that helps an agent use Entire history, checkpoints, and session context for a specific task. | | **Token usage** | Counts of input tokens, output tokens, cache creation tokens, cache reads, and API calls recorded for a checkpoint or session. | | **Trail** | Entire's unit of work, covering one branch and one pull request from one intent to shipped code. A trail groups that intent, the [checkpoints](/glossary#checkpoint) recorded along the way, and a rolled-up summary and report. Teams review the trail instead of the raw diff. | | **Worktree ID** | An opaque identifier Entire puts in a shadow branch name to tell active worktrees apart. | No glossary terms match your filter. # Overview Source: https://docs.entire.com/guides/brain/overview Give your coding agents shared memory of your project, past decisions, and lessons learned. ## What Is entire-brain? entire-brain is a memory layer for your Git repository. It brings together saved agent sessions, checkpoints, project memories, documentation, and code context from [entire-graph](/guides/graph/overview). entire-graph maps how your code connects while entire-brain adds the context behind it: why a decision was made, what was tried before, and what your team learned. That memory belongs to the project and different coding agents can use it. For example, you can move from Claude Code to Codex and give the next agent context from earlier work. [Entire Brain: Give Your Repository a Shared Memory](https://www.youtube.com/embed/c3ZCSBMD9wM) ## How Does It Help? entire-brain is great for team collaboration and individual work when you are context switching across tasks and agents. It helps you spend less time explaining your project and repeating earlier research. A new agent session can start with the decisions, rules, and lessons that have already been recorded. For example, before changing how failed requests are retried, you can ask entire-brain for earlier decisions about retries. Your agent can use that context to understand the current approach before editing the code. ## What Can You Do with entire-brain? * Understand a project to get an overview of its structure and how it works. * Prepare for a task and find relevant decisions, code locations, and possible tests. * Find earlier work by searching through saved memories, history, and documentation, including PDF, Word, Excel, and PowerPoint files under `docs/`. * Record a project rule or decision for future sessions, or a global memory that applies in every repository. * Browse what entire-brain knows in a local UI. * Sync memories with your hosted Entire repository when you choose to connect it. ## Before You Start Use a local Git repository with at least one commit. Install the [Entire CLI](/installation) and Git 2.36 or later. To give entire-brain access to future agent sessions, [enable Entire in your repository](/quickstart). entire-brain can also work from code, docs, and Git history when no saved sessions are available. Make sure to commit your intended changes before setup. ### Install entire-brain Run this once on your machine: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/entireio/entire-brain/main/scripts/get-brain.sh | bash ``` The installer downloads a prebuilt binary, checks its checksum, and registers the `entire brain` command. entire-brain uses [entire-graph](/guides/graph/overview) for code analysis, and it is part of the default install: entire-brain declares entire-graph as a required plugin, so `entire plugin install brain` offers to install it in the same run. The script installer above cannot show that prompt, so it prints a reminder instead — after it finishes, install entire-graph yourself: ```bash theme={null} entire plugin install graph ``` entire-brain reads code context from entire-graph's shared code index. Running without entire-graph is a degraded mode, not the default: `entire brain setup` reports the code index as unavailable, `entire plugin doctor` reports the missing dependency, and code context is missing from answers. Searching sessions, docs, and memories still works, and `brief` still runs. > [!NOTE] > > You need to [update the Entire CLI](/installation#install-and-update-entire) to 0.11.6 or later and run `entire plugin upgrade graph` first, then rerun the entire-brain installer above. After upgrading, rerun `entire brain setup` in each repository to refresh `.entire/agent-guide.md`, and commit the updated files. > > The `entire brain facts` commands are now `entire brain memories`, and `facts` still works as an alias. `entire brain init-agents` has been removed, `entire brain setup` now adds the agent instructions. ### Set Up Your Repository Open the project repository where you want to use entire-brain. If you installed entire-brain from source, switch from the `entire-brain` source directory to your project first. From your project's root, run: ```bash theme={null} entire brain setup entire brain status ``` Setup builds the repository's memory, installs a background watcher to keep it current, and adds the instructions that tell your coding agent how to use entire-brain. Status shows what is ready and what needs attention. Setup prints a short summary. Add `--verbose` to see the full report for each phase. > [!NOTE] > > Setup asks before it extracts memories from past sessions, and the default answer is no. Memory extraction uses an available coding agent, can send session content to its model provider, and can add token charges. When setup runs without a terminal, for example in a script, it skips extraction unless you pass `--yes`. > > Setup remembers what you decline, so rerunning it does not ask again. To turn a declined step back on, pass `--backfill` for memory extraction, `--daemon` for the background watcher, or `--agent-hooks` for Claude Code hooks. > > To skip memory extraction and the background watcher entirely, use `entire brain setup --no-backfill --no-daemon`. #### Agent Instructions Setup creates or updates `.entire/agent-guide.md` and adds references to it in `AGENTS.md` and `CLAUDE.md`. Text outside the managed blocks is preserved. Rerunning setup replaces the generated guide. | Flag | What it does | | - | - | | `--strict` | Saves strict guidance that makes using entire-brain's tools mandatory for your agent. | | `--normal` | Resets the guide to normal guidance. | | `--no-agent-hooks` | Writes the guide but does not add the entire-brain hook to Claude Code's settings. | | `--agent-hooks` | Adds the Claude Code hook, even if an earlier run declined it. | To preview the instructions without changing any files, run `entire brain agent-guide`. Review and commit the generated files to share the instructions with your team. Restart your agent or reload its repository instructions so it picks up the guide. The guide includes instructions for each product you have set up. The default setup includes both products, so also run `entire graph setup` to add the entire-graph instructions. You can run the two setups in either order. #### Connect an MCP Client If your agent uses MCP, print the configuration from your project repository: ```bash theme={null} entire brain mcp --print-config ``` Add that configuration to your MCP client. For Claude Code, you can register entire-brain with: ```bash theme={null} claude mcp add entire-brain -- entire brain mcp ``` Over MCP, agents can save memories with `brain_remember` and retrieve them with `brain_recall`, along with tools such as `brain_brief`, `brain_query`, and `brain_status`. By default, the MCP server uses stdio. To also serve it over HTTP, pass an address: ```bash theme={null} entire brain mcp --http 127.0.0.1:7777 ``` The HTTP listener binds to loopback unless you add `--http-allow-remote`, and it always requires a bearer token. Set `ENTIRE_BRAIN_MCP_TOKEN` to supply your own token, or entire-brain generates one and prints it at startup. The same listener serves a read-only REST API under `/v1/` that uses the same bearer token: | Endpoint | Returns | | - | - | | `GET /v1/status` | Memory freshness and source counts | | `GET /v1/facts` | Saved memories. Accepts `limit` and `branch`. | | `GET /v1/search?q=` | Search results. Accepts `limit` and `source`. | > [!NOTE] > > The REST path is still `/v1/facts`, from before facts were renamed to memories. ## How to Use entire-brain Use entire-brain from the CLI or UI after setup, or use the agent prompt to have your agent set it up for you. **CLI** Run these commands from your repository. Get a project overview: ```bash theme={null} entire brain overview ``` Get context for a task: ```bash theme={null} entire brain brief "update the retry policy" ``` Search earlier decisions: ```bash theme={null} entire brain query "why did we choose this retry policy" ``` Save a memory, then find it again. Replace the example with a rule that is true for your project: ```bash theme={null} entire brain remember "Retry failed requests at most three times." --path constraints.retry.policy entire brain recall "retry policy" ``` Check whether memory is current: ```bash theme={null} entire brain status ``` If something needs attention, `entire brain doctor` reports the problem and the command that fixes it. See the [command reference](https://github.com/entireio/entire-brain/blob/main/docs/reference.md) for more options. To list every command, including developer commands hidden from the default help, run `entire brain --help-all`. **UI** Open entire-brain's local browser view from your repository: ```bash theme={null} entire brain viz ``` Explore the graph to see code relationships, saved memories, sessions, history, and docs. This view runs on your machine and is read-only. [Explore entire-brain in the UI](https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/988f4fb499040d1c5b3cc2417046e720/iframe) If you prefer to stay in your terminal, open the dashboard: ```bash theme={null} entire brain dash ``` ![entire-brain terminal dashboard showing memory sources, session counts, saved memories, and working tree status.](https://mintcdn.com/entire/C8ICUvcRVo-DnEOP/images/brain-terminal-dashboard.png?fit=max\&auto=format\&n=C8ICUvcRVo-DnEOP\&q=85\&s=2c6b1fb2747bc2b01c577e7de66ac168) Use it to browse status, memories, sessions, history, and code records. Both views let you explore existing memory without making model calls. **Agent Prompt** To have your agent set up entire-brain for you, open it in your repository and send this prompt: ```text theme={null} Set up entire-brain in this repository and start using it for our work. Check that the Entire CLI, Git 2.36 or later, and entire-graph are installed. Install any missing tools using the official instructions at https://github.com/entireio/entire-brain#install. Make sure this is a Git repository with at least one commit. If there are uncommitted changes that block setup, tell me what needs attention. Run `entire brain setup --no-backfill` to build the project's memory and add the agent instructions. Preserve my existing instructions outside the managed blocks. Ask me before running a memory backfill, because it uses a coding agent and can incur token charges. Run `entire brain status --verbose` and explain anything missing or out of date. Read `.entire/agent-guide.md`, then run `entire brain overview` and summarize what entire-brain knows about this project. For my next task, use `entire brain brief` to gather relevant context before making changes. Check the supporting sources and use entire-graph to find and inspect the code. ``` ## Pause Background Work The background watcher and the session-end hook keep memory current and can call a coding agent to extract memories. To pause all background entire-brain work on your machine, run: ```bash theme={null} entire brain stop ``` Work already in progress finishes first. Captured sessions are not lost; entire-brain picks them up when you resume: ```bash theme={null} entire brain start ``` To remove the watcher instead, run `entire brain setup --uninstall-daemon`. ## Sync Memories with Entire Memories stay on your machine by default. A repository starts syncing only when you connect it to its hosted Entire repository: ```bash theme={null} entire brain connect ``` `connect` records the hosted repository, then runs one sync right away. After that, the background watcher syncs memories automatically. Connecting requires Entire CLI 0.11.6 or later. To stop syncing, run: ```bash theme={null} entire brain disconnect ``` You can also sync on demand with `entire brain memories sync`. In a repository that is not connected, the command fails and tells you to run `connect`. # Getting started with Brain Source: https://docs.entire.com/guides/brain/quickstart Learn what you can do with Brain and find the right command for each task. You can use Brain to find earlier decisions, save lessons, and give your agent context before it starts work. Below are some ways to use Brain in your project. [Install Brain and set up your repository](/guides/brain/overview#before-you-start) first. Run these commands from the repository, and replace the example questions and rules with your own. ## Get to Know a Project If you are joining a project or returning after a break, you can ask Brain for an overview of its structure, tools, and conventions. ```bash theme={null} entire brain overview ``` ## Get Context Before Starting a Task Describe what you want to build or change. Brain gathers relevant memories, earlier work, code locations, and possible tests into a brief. ```bash theme={null} entire brain brief "add rate limiting to the upload endpoint" ``` You can now use the brief to plan your work or give your coding agent a starting point. Code locations in the brief come from entire-graph. ## Find Out Why a Decision Was Made Search earlier work before reopening a decision or trying an approach your team has already explored. ```bash theme={null} entire brain query "why did we remove the queue abstraction" ``` This helps you read the supporting sources to understand the decision and whether it still applies. ## Search for a Topic Search for a topic by the words you expect to appear in saved memories, history, or docs: ```bash theme={null} entire brain query "rate limiter" ``` `query` ranks results by keyword relevance using BM25, so results match the words in your query rather than their meaning. If a search returns nothing useful, try the terms your team would have used when the decision was recorded. The `--semantic` flag is deprecated and has no effect. It is still accepted as an alias so existing scripts keep working, but it returns the same keyword-ranked results. To narrow the search to one kind of source, use `--source` with `fact`, `history`, or `doc`: ```bash theme={null} entire brain query "rate limiter" --source fact ``` To rank recent results higher, add `--recency`. You can change how quickly older results lose weight with `--recency-half-life`, which defaults to `2160h` (90 days): ```bash theme={null} entire brain query "rate limiter" --recency --recency-half-life 720h ``` ## Save a Rule for Future Work You can also record a decision or lesson as a memory so another session can find it. Only save rules that are true for your project. ```bash theme={null} entire brain remember "Retry failed requests at most three times." --path constraints.retry.policy ``` The path flag groups the memory under a topic. This lets you save the memory without asking an agent to choose a category. ## Save a Rule for Every Repository Some memories, such as a personal preference or a team convention, apply to every repository you work in. Record them globally: ```bash theme={null} entire brain remember "The staging cluster is in eu-west-1." --global ``` Brain recalls global memories from every repository and labels them `(global)` in results. To list them: ```bash theme={null} entire brain memories global ``` To leave global memories out of a search, add `--no-global` to `query` or `recall`. ## Look Up Saved Rules Before changing behavior, you can check what your project has already recorded about it. ```bash theme={null} entire brain recall "retry policy" ``` Use `recall` for saved memories and `query` for a broader search across memories, history, and docs. ## Review Memories as Markdown Files Write your memories out as one Markdown file per memory, so you can read, search, and diff them with your usual tools: ```bash theme={null} entire brain memories files --dir brain-memories ``` The files are a copy. Brain rewrites the directory on each run and does not read the files back, so use `remember` and `memories retract` to change memories. ## Import Memories from Another Tool If you have memories in mem0, import its export file. Preview the import first: ```bash theme={null} entire brain memories import --file mem0-export.json --dry-run entire brain memories import --file mem0-export.json ``` Imported memories are filed under `project.imported` by default. Change this with `--path-prefix`. ## Search Documents That Are Not Code Brain reads PDF, Word, Excel, and PowerPoint files under `docs/` along with Markdown, so they come back from `query` and `brief`. Extraction runs locally, with no model or network calls. To check what Brain reads from a file: ```bash theme={null} entire brain docs extract docs/spec.pdf ``` Scanned PDFs have no text layer, so Brain reports them instead of indexing an empty document. ## Check What a Code Change Could Affect With entire-graph installed, inspect the impact of changing a function or type. Replace `ValidateToken` with a symbol from your code. ```bash theme={null} entire brain inspect impact ValidateToken ``` You can also inspect changes since the last index: ```bash theme={null} entire brain inspect changes ``` ## Notify Another Service When Memory Changes Brain can send a JSON event to an HTTP endpoint when a memory is recorded or retracted, or when memory is refreshed. This lets a CI job, chat channel, or index react without polling. ```bash theme={null} export ENTIRE_BRAIN_WEBHOOK_URL=https://hooks.example.com/entire export ENTIRE_BRAIN_WEBHOOK_SECRET=a-long-random-string entire brain webhook test ``` | Variable | What it does | | - | - | | `ENTIRE_BRAIN_WEBHOOK_URL` | Endpoint to send events to. Webhooks are off when it is unset. | | `ENTIRE_BRAIN_WEBHOOK_SECRET` | Signs each request with HMAC-SHA256 in the `X-Entire-Signature-256` header. | | `ENTIRE_BRAIN_WEBHOOK_INCLUDE_TEXT` | Set to `1` to include memory text in events. Text is left out by default. | | `ENTIRE_BRAIN_NO_EGRESS` | Turns off all webhooks, along with other network calls. | Run `entire brain webhook events` to list the events Brain sends. ## Check Whether Memory Is Current You can see which sources are available, missing, or out of date, using: ```bash theme={null} entire brain status --verbose ``` If something needs attention, `doctor` prints the command that fixes it: ```bash theme={null} entire brain doctor ``` Check whether saved memories still point to matching sources: ```bash theme={null} entire brain verify ``` A memory entered by hand can show `unverifiable-here` because it has no source reference. Verification checks references, not whether a memory is correct. # Capture Sessions and Their Checkpoints Source: https://docs.entire.com/guides/checkpoints/capture-checkpoints Learn how Entire captures agent sessions and turns them into committed checkpoints. Entire captures session context while you work, then creates a committed checkpoint when that context is linked to a Git commit. ## How Capture Works Checkpoint capture has two parts: 1. [Agent hooks](/agents/overview) collect session context, including prompts, transcript, tool activity, changed files, and token usage when available. 2. Git hooks link that captured context to a commit by adding an [`Entire-Checkpoint` trailer](/glossary#entire-checkpoint). After the commit, Entire stores checkpoint metadata in your repository, in [its own Git ref or on the checkpoints branch](/security#where-your-data-lives) depending on the [storage backend](/guides/checkpoints/checkpoint-storage). Your working branch stays clean. ## Set Up Capture for an Agent For a new repository, enable Entire with the agent you use: ```bash theme={null} entire enable --agent AGENT ``` For a repository where Entire is already enabled, add another agent: ```bash theme={null} entire agent add AGENT ``` You can see the supported built-in agents in [Agents](/agents/overview), or run: ```bash theme={null} entire agent list ``` ## Commit After Agent Work To capture agent-assisted work in a checkpoint: 1. Start your agent from an Entire-enabled repository. 2. Ask the agent to make a change. 3. Stage and commit the change with Git. ```bash theme={null} git add . git commit -m "Describe the change" ``` If Entire detects recent agent work, it may ask whether to link the commit to the session context. Choose `yes` to create the checkpoint. Choose `always` if you want Entire to remember that preference for future matching commits. ```text theme={null} Entire: Active Codex session detected Last prompt: Add a user settings page... Link this commit to session context? [Y]es / [n]o / [a]lways (remember my choice): ``` ## Link Future Commits Automatically When the "Link this commit to session context?" prompt appears during `git commit`, choosing `yes` or `no` only applies to that one commit. To link future matching commits in this repository without being prompted during `git commit`, set `commit_linking` to `always`. Set `commit_linking` in one of these files: * `.entire/settings.local.json` if this preference should only apply to you * `.entire/settings.json` if this should be the team setting for the repository ```json theme={null} { "commit_linking": "always" } ``` ## Let the Agent Commit Your agent can also create commits for you. For example, you might ask it to make a focused change and commit when it is done. Entire still uses the Git hooks to link the commit to the captured session context. If the agent makes several commits in one session, each commit gets its own checkpoint. ## Capture Multiple Commits from One Session A single agent session can produce multiple checkpoints. This happens when a long session creates several commits, or when you split the agent's work into smaller commits yourself. Each commit gets its own checkpoint ID. The checkpoints can share the same session context so you can still inspect the prompts, transcript, and work that led to each commit. ## Capture One Checkpoint from Multiple Sessions One checkpoint can also include more than one session. This happens when several agent sessions contribute to the work before you make a single commit. In entire.com, those sessions appear together inside the checkpoint's Sessions tab. The checkpoint diff shows the combined change, while [session details](/guides/sessions/sessions-in-entire-com) show the context behind each contribution. ## What Does Not Create a Checkpoint Entire needs captured session context and a Git commit to create a normal committed checkpoint. A checkpoint may not appear when: * Entire has not been enabled in the repository * agent hooks were not installed for the agent you used * the agent did not change files in the repository * no commit was created * a GUI Git client could not find the `entire` command from its Git hooks If a checkpoint is missing or did not link where you expected, see [Troubleshooting](/guides/sessions/troubleshooting). # Choose Where Checkpoints Are Uploaded Source: https://docs.entire.com/guides/checkpoints/checkpoint-destination Control which remote receives checkpoint data when a repository has several. Entire uploads checkpoints to one place, the checkpoint destination. It is either: * **One of your existing remotes**, chosen automatically or pinned with `--checkpoint-push-remote `. Checkpoints are uploaded when you run `git push` to that remote. * **A separate checkpoint repository**, set with `--checkpoint-remote`. See [Store Checkpoints in Another Repository](/guides/checkpoints/store-checkpoints-in-another-repo). The two flags differ by one word but mean different things: `--checkpoint-push-remote` picks which of your remotes receives checkpoints, while `--checkpoint-remote` sends them to a different repository altogether. `entire status` shows the current destination, where it came from, and how many checkpoints are unpushed. With the default `git-refs` [storage backend](/guides/checkpoints/checkpoint-storage), `entire checkpoint list --outgoing` lists them. Every `entire enable` run ends by naming the destination. ## Which Remote Receives Checkpoints If you push code to several remotes, checkpoints go to exactly one of them. Entire picks it in this order: 1. `strategy_options.checkpoint_push_remote`, if set. If it names a remote that isn't configured, checkpoints don't sync. 2. The remote of your first push whose target matches the branch's configured push destination. Entire announces the choice and keeps it. 3. `origin` 4. The sole remote, if the repository has exactly one 5. The first remote in `.git/config` order A push to any other remote carries no checkpoint data, unless every push URL of both remotes names the same GitHub repository. For example, `git@github.com:acme/widgets.git` and its Entire mirror `entire:///gh/acme/widgets` reach the same repository, so a push to either carries the checkpoints. ## Choose the Remote When a repository has several remotes that could receive checkpoints, the first interactive `entire enable` asks which one to use, after agent selection and before any hooks or settings are written. Running `entire enable` again in an enabled repository does not ask again. Choosing a remote saves `strategy_options.checkpoint_push_remote` in `.entire/settings.local.json`, so teammates do not inherit a remote name specific to your clone. Keeping the current destination writes nothing. To select a remote without the picker: ```bash theme={null} entire enable --yes --checkpoint-push-remote fork ``` The remote must already exist. Use the same command to change the destination later, or to repair a saved selection that names a missing remote. An explicit flag pins the named remote, even if it is currently selected automatically. `--yes` alone does not change the destination. Selecting a destination does not re-enable disabled checkpoint pushing, upload existing checkpoints immediately, or move or delete checkpoint history on other remotes. ## Edge Cases * An SSH host alias from `~/.ssh/config`, such as `git@github-work:acme/widgets.git`, counts as GitHub when Git runs plain `ssh`. With a custom `GIT_SSH_COMMAND` or `core.sshCommand`, the alias cannot be resolved, so it does not match. * `entire enable` always says where checkpoints will be uploaded. When you chose the destination, it also says how. If a saved destination is unusable, it reports the problem instead of showing the privacy notice, unless checkpoints still upload to a dedicated checkpoint repository. # Session Storage Source: https://docs.entire.com/guides/checkpoints/checkpoint-storage Where Entire stores your session and the checkpoints that are linked with your commits. Entire stores checkpoints inside your own Git repository, separate from your source branches. Your code stays on your source branches, while prompts, transcripts, session context, and checkpoint metadata live in checkpoint storage. Most of this happens behind the scenes, so your workflow stays the same: you create, search, explain, and resume checkpoints with the same Entire commands regardless of how they are stored. > [!NOTE] > > We verified this page against **Entire CLI 0.10.2**. Run `entire version` to check what you have installed. ## Store Checkpoints with Your Code This is the default and needs no configuration. Entire stores checkpoint data in the same Git repository as your code and pushes it when you push, which keeps the commit, the checkpoint, and the agent context together while leaving your normal Git history clean. In a repository with several remotes, Entire elects one checkpoint sync remote rather than copying checkpoints everywhere you push. `entire status` names the destination and counts checkpoints that have not reached it. This can be changed if you want your checkpoint and session storage history to reside elsewhere: * [**Push checkpoints to a separate repository**](/guides/checkpoints/store-checkpoints-in-another-repo) * [**Keep checkpoints local on your machine**](/guides/checkpoints/keep-checkpoints-local) ## The Two Storage Backends The backend controls how Git organizes checkpoint data. It is a separate question from which repository receives that data. ### Ref-Based Storage Ref-based storage (`git-refs`) is the default. It gives each new checkpoint its own Git ref, a named pointer inside your repository that Entire creates and manages for you. Each ref lives at `refs/entire/checkpoints//`, and Entire saves and retrieves each checkpoint independently. **The benefit:** With ref-based storage, pushes and reads stay fast even as your repository accumulates more agent history. Multiple agents can also save their work at the same time without competing to update a shared branch. Ref-based checkpoints use 26-character, time-sortable ULIDs, such as `01KVBJCWYA4YW6J5M9GP655HZN`. Ref-based storage first shipped as an opt-in option in Entire CLI 0.8.42 and became the default in 0.10.0, where `entire enable` writes it during a first-time setup and no longer asks you to choose. ### Branch-Based Storage Branch-based storage (`git-branch`) keeps every checkpoint on a shared Git branch called [`entire/checkpoints/v1`](/glossary#checkpoints-branch). Each checkpoint sits at `//` in the branch tree. **The benefit:** All checkpoint history lives on one branch you can check out, browse, or clone like any other branch. Branch-based checkpoints use 12-character hexadecimal IDs, such as `a3b2c4d5e6f7`. A repository you enabled before Entire CLI 0.10.0 uses branch-based storage and stays on it until you [switch backends](#switch-backends). ## Find Which Backend a Repository Uses The backend is named by `checkpoints.primary.type` in `.entire/settings.json`, or in `.entire/settings.local.json` when someone set it for their clone alone. An absent `checkpoints` block resolves to `git-branch`, which is why a pre-0.10.0 repository keeps branch storage without any setting naming it. Checkpoint storage is ordinary Git, so Git reads it without Entire installed. List the per-checkpoint refs: ```bash theme={null} git for-each-ref refs/entire/checkpoints/ ``` Each line names one checkpoint, where `` is the last two characters of the ID and `` is always the leaf. Check for branch-backed checkpoints too: ```bash theme={null} git show-ref entire/checkpoints/v1 ``` Output from both means the repository holds checkpoints in both formats, which is the expected state after a backend switch. To confirm what reached the remote, run `git ls-remote origin 'refs/entire/checkpoints/*'`. ## Both Backends Stay Readable Every reader routes by ID format, so one repository can hold both formats at once. This holds for the CLI, entire.com, and the Entire API. | Checkpoint ID | Where the read goes | | - | - | | ULID | Refs only. ULIDs are minted only under ref-based storage | | Hex, branch-based backend | The `entire/checkpoints/v1` branch | | Hex, ref-based backend | Refs first, then the branch, since a hex checkpoint may still sit on the pre-switch branch | `entire checkpoint list` merges both backends and de-duplicates by ID. A new checkpoint goes to the configured backend, while a backfill that adds a transcript, summary, or attribution to an existing checkpoint lands in whichever backend already holds it. ## Switch Backends To enable ref-based storage in a new repository, run: ```bash theme={null} entire enable --checkpoint-backend refs ``` To enable it in an existing Entire-enabled repository, run: ```bash theme={null} entire configure --checkpoint-backend refs ``` Both commands accept `refs` and `branch`, plus the canonical `git-refs` and `git-branch` that settings store. Add `--local` when the choice should apply only to your clone. A switch applies to new checkpoints. Checkpoints written before the switch stay exactly where they are and keep resolving through the routing above, so `entire checkpoint list`, `entire checkpoint explain`, attribution, and entire.com continue to serve them. Entire deletes nothing during a switch, and your commands and commit workflow do not change. Two things do change after a switch to ref-based storage. New checkpoint IDs become ULIDs instead of hex, and the pre-push hook starts pushing queued per-checkpoint refs instead of the `entire/checkpoints/v1` branch. Leave that branch on the remote: it is where readers find every checkpoint captured before the switch. ## Migrate Existing Checkpoints into Refs Migration is optional, since the routing above already resolves branch-backed checkpoints under a ref-based backend. Migrate when you want the whole history in one format, or when you want to stop carrying the v1 branch. > [!WARNING] > > Run the migration **before** you switch the backend to refs. The command refuses to run once ref-based storage is primary, because the refs are authoritative at that point and re-importing branch snapshots could only move them backwards. ```bash theme={null} entire doctor migrate-checkpoints --dry-run entire doctor migrate-checkpoints ``` The command wraps each checkpoint's current tree in a fresh commit and points its ref at it, keeping the hex ID as the ref name. It does not rewrite the branch commits, and it does not delete the branch. It skips checkpoints it has already converted, so you can re-run it after more branch activity. | Flag | Description | | - | - | | `--dry-run` | Report what would be migrated without writing refs | | `--remote NAME` | Push migrated refs to this remote instead of the checkpoint sync remote | Migrated refs are queued for push. Run interactively, the command asks whether to push them now. Run without a terminal, it leaves them queued, and they flush on the next `git push` once ref-based storage is primary. Then switch and push: ```bash theme={null} entire configure --checkpoint-backend refs git push ``` ## Auto-Generate Checkpoint Summaries Checkpoint metadata can carry a summary generated at commit time. Enable it with `strategy_options.summarize.enabled`: ```json .entire/settings.json theme={null} { "strategy_options": { "summarize": { "enabled": true } } } ``` Then choose the provider and model: ```bash theme={null} entire configure --summarize-provider PROVIDER entire configure --summarize-model MODEL ``` Without a configured provider, commit-time summaries use Claude Code (`claude` on your `PATH`, model `sonnet`). `entire checkpoint explain --generate` instead picks an installed agent that can write summaries, asks when there are several, and saves your choice. Factory AI Droid cannot generate summaries. ## Where Storage Settings Are Saved `entire configure` writes to `.entire/settings.json` by default, so the repository shares the setting. Add `--local` to write `.entire/settings.local.json` instead, which applies only to your clone and takes precedence over project settings. The `checkpoints` block is a selection, not a merged document: a `checkpoints` block in `.entire/settings.local.json` replaces the one in `.entire/settings.json` outright. The `strategy_options` keys merge by layer as usual. See [Local, Project, and Global Settings](/guides/configuration/settings-layers) for the full table. ## Continue With > **[Store Checkpoints in Another Repository](/guides/checkpoints/store-checkpoints-in-another-repo)** > > Push checkpoint history to a repository separate from your code. > **[Keep Checkpoints Local](/guides/checkpoints/keep-checkpoints-local)** > > Capture checkpoints without pushing them anywhere. > **[Security and Privacy](/security#where-your-data-lives)** > > See every location Entire writes to and what redaction covers. > **[Checkpoint Troubleshooting](/guides/sessions/troubleshooting)** > > Fix checkpoints that did not sync or landed in the wrong place. # Inspect Checkpoints Source: https://docs.entire.com/guides/checkpoints/inspect-checkpoints Choose how to inspect checkpoint context in entire.com or the Entire CLI. Use this page when you want to see what happened behind a checkpoint: the commit, prompt, transcript, sessions, files, token usage, and attribution. > [!NOTE] > > Inspecting a checkpoint reads history that Entire already captured. [`entire review`](/cli-reference/review) is a different command: it runs a multi-agent review against your current branch. ## Choose a Surface | Use this | When you want to | | - | - | | [**entire.com**](/guides/checkpoints/inspect-in-entire-com) | Browse checkpoints by repository and branch, inspect sessions visually, read file diffs, or share context with a team. | | [**Entire CLI**](/guides/checkpoints/inspect-in-cli) | Work from a terminal, explain a checkpoint or commit, read transcript output, compare token usage, or export JSON. | ## What to Look For When you open a checkpoint, check: * the original prompt or task * the transcript and tool calls * files changed by the agent * file diffs and line attribution * token usage and session metadata * whether the checkpoint is linked to the commit you expected ## Continue With > **[Inspect in entire.com](/guides/checkpoints/inspect-in-entire-com)** > > Open checkpoint details, sessions, and file diffs visually. > **[Inspect in the CLI](/guides/checkpoints/inspect-in-cli)** > > List, explain, and measure checkpoints locally. > **[Sessions in entire.com](/guides/sessions/sessions-in-entire-com)** > > See the transcript and tool calls behind a checkpoint. > **[Search Past Work and Code](/learn/search-past-agent-work)** > > Find previous checkpoints, sessions, and commits by meaning. # Inspect Checkpoints in CLI Source: https://docs.entire.com/guides/checkpoints/inspect-in-cli List, explain, and measure checkpoints from a terminal. Use the Entire CLI when you want to work from a terminal, explain a checkpoint or commit, read transcript output, compare token usage, or export checkpoint data as JSON. ## Find a Checkpoint List checkpoints on the current branch: ```bash theme={null} entire checkpoint list ``` Add `--json` for a machine-readable listing, or `--session ID` to narrow the list to one session. When you do not know which checkpoint you want, search by phrase, meaning, or context: ```bash theme={null} entire checkpoint search "what changed" ``` ## Explain a Checkpoint or Commit Explain a checkpoint by ID, or by an unambiguous prefix of one: ```bash theme={null} entire checkpoint explain CHECKPOINT_ID ``` A commit-ish works too, and resolves through the commit's `Entire-Checkpoint` trailer: ```bash theme={null} entire checkpoint explain HEAD~3 ``` Add `--full` for the whole parsed transcript, `--raw-transcript` for the JSONL file, or `--short` for the summary alone. ## Generate a Summary Generate an AI summary for the checkpoint: ```bash theme={null} entire checkpoint explain CHECKPOINT_ID --generate ``` The `--generate` flag requires the configured provider CLI to be installed and authenticated. ## Measure Token Usage Report token usage and optimization recommendations for a checkpoint: ```bash theme={null} entire checkpoint tokens CHECKPOINT_ID ``` The report names the checkpoint, the sessions and agents behind it, the models they used, and the branch, followed by the usage breakdown and the recommendations drawn from it. It reads committed checkpoint metadata through the same resolution path as `entire checkpoint explain`, so an ID prefix or a commit-ish works here as well, and metadata missing locally is fetched from the checkpoint remote. Compare a checkpoint against an earlier one to see how usage moved: ```bash theme={null} entire checkpoint tokens CHECKPOINT_ID --compare BASELINE_ID ``` The comparison reports total tokens, input, cache and context replay, cache write, output, and API calls as a delta against the baseline, and qualifies whether the change counts as an observed reduction or increase. | Flag | Description | | - | - | | `--json` | Output the full report as JSON | | `--compare ID` | Compare against a baseline checkpoint | | `--agent-brief` | Print compact next-step guidance for an agent | `--json` and `--agent-brief` are mutually exclusive. ## Continue With > **[Inspect in entire.com](/guides/checkpoints/inspect-in-entire-com)** > > Open checkpoint details, sessions, and file diffs visually. > **[checkpoint](/cli-reference/checkpoint)** > > See the full checkpoint command reference. # Inspect Checkpoints in entire.com Source: https://docs.entire.com/guides/checkpoints/inspect-in-entire-com Open checkpoint details, sessions, and file diffs in entire.com. Use entire.com when you want to browse checkpoints visually, inspect sessions, read diffs, or share checkpoint context with a team. Open [entire.com](https://entire.com), then open the repository that contains the checkpoint. ## Open a Checkpoint 1. Choose the branch you want to inspect. 2. Find the commit with the checkpoint. 3. Open the checkpoint detail view. 4. Use **Sessions** to inspect the prompt, transcript, tool activity, and session metadata. 5. Use **Changes** to read the files and diff connected to the checkpoint. ## Branch View Open a repository to see its branch list. Each branch shows recent commits grouped by day, with checkpoints captured on each commit. Each checkpoint row shows: * commit SHA * commit message * agent * code changes * checkpoint count, when more than one checkpoint is attached * author ## Checkpoint Detail Open a checkpoint to inspect the detail view. ![Checkpoint detail view in entire.com](https://mintcdn.com/entire/fgG56b7zcMZgFdOf/images/checkpoint-detail-dark.png?fit=max\&auto=format\&n=fgG56b7zcMZgFdOf\&q=85\&s=f8cc696d48c8623b660e60a61be165d1) The header shows the commit SHA, branch, author, agent, file count, AI percentage, and token usage when available. The detail view has two main tabs: * **Sessions**: prompts, transcript, tool activity, session metadata, and any sessions that contributed to the checkpoint * **Changes**: modified files, with a file tree and diff view Use **Alt + Left Arrow** and **Alt + Right Arrow** to move to the previous or next checkpoint on the same branch. ## Open from a Commit You can open a checkpoint from a commit URL: ```text theme={null} https://entire.com/gh///commit/ ``` When a commit has an `Entire-Checkpoint` trailer, the checkpoint ID also appears in the commit message: ```text theme={null} fix: handle empty repos in dispatch generation Entire-Checkpoint: 01KVBJCWYA4YW6J5M9GP655HZN ``` You can also open a checkpoint from a session when that session produced or contributed to the checkpoint. ## Continue With > **[Inspect in the CLI](/guides/checkpoints/inspect-in-cli)** > > List, explain, and measure checkpoints locally. > **[Sessions in entire.com](/guides/sessions/sessions-in-entire-com)** > > See the transcript and tool calls behind a checkpoint. # Keep Checkpoints Local Source: https://docs.entire.com/guides/checkpoints/keep-checkpoints-local Capture checkpoint history without pushing it to a remote repository. When checkpoint history should stay on the machine that captured it, turn off automatic checkpoint pushes. Entire keeps capturing checkpoint data and stops sending it to GitHub or another remote. Use this for local experiments, or for repositories where you do not need checkpoint history available from another device. The tradeoff is that teammates cannot open a local-only checkpoint, and neither can you from another machine. ## Just Your Clone Write the setting to local settings: ```bash theme={null} entire configure --local --skip-push-sessions ``` This writes `push_sessions: false` to `.entire/settings.local.json`: ```json .entire/settings.local.json theme={null} { "strategy_options": { "push_sessions": false } } ``` `.entire/settings.local.json` is gitignored and takes precedence over project settings, so nobody else in the repository is affected. ## The Whole Repository To disable checkpoint pushes for everyone working in the repository, use project settings instead: ```bash theme={null} entire configure --project --skip-push-sessions ``` This writes the same setting to `.entire/settings.json`. Commit that file when the behavior should apply to the whole project. See [Local, Project, and Global Settings](/guides/configuration/settings-layers) for how the layers resolve. ## Turn Pushing Back On `--skip-push-sessions` only sets the flag; there is no flag that clears it. Set `push_sessions` back to `true` in the settings file you wrote it to, or delete the key to fall back to the default: ```json .entire/settings.local.json theme={null} { "strategy_options": { "push_sessions": true } } ``` `entire status` then names the checkpoint sync destination and counts the checkpoints waiting to reach it. # Store Checkpoints in Another Repository Source: https://docs.entire.com/guides/checkpoints/store-checkpoints-in-another-repo Push checkpoint history to a repository separate from your source code. Configure a [checkpoint remote](/glossary#checkpoint-remote) when checkpoint history should follow a different sharing boundary than your source code, such as keeping agent transcripts private for a public project. Your code continues to live in the main repository, and Entire pushes checkpoint data to the separate one. ## Configure the Checkpoint Remote Create a separate, empty repository for checkpoint data, then run this from your project: ```bash theme={null} entire configure --checkpoint-remote github:owner/repo ``` The value uses the format `provider:owner/repo`, where the provider is `github` or `gitlab`. This writes: ```json .entire/settings.json theme={null} { "strategy_options": { "checkpoint_remote": { "provider": "github", "repo": "owner/repo" } } } ``` Commit and push `.entire/settings.json` when the checkpoint remote should apply to the whole project. That setting is what entire.com reads to locate checkpoint data. ## Keep Checkpoints under the Same Owner Use a checkpoint repository with the same owner or organization as your code repository. Code at `github.com/acme/app` pairs with `github:acme/app-checkpoints`, because `acme` owns both. A committed `checkpoint_remote` is inherited by everyone who clones or forks the project. To keep a contributor's session data out of the upstream project's checkpoint repository, Entire ignores the setting when it looks inherited, and uploads checkpoints to the remote you push to instead, following the rules in [Choose Where Checkpoints Are Uploaded](/guides/checkpoints/checkpoint-destination). `entire status` shows when and why the setting is ignored. Entire treats the setting as yours when either of these is true: * It is in the gitignored `.entire/settings.local.json`. * Your `origin` and every push URL of the remote you push to are owned by the same account or organization as the checkpoint repository. Requiring the push remote as well covers contributors who cloned the upstream repository and added their own fork, where `origin` belongs to the upstream project. If your checkpoint repository is owned by a different account or organization than your code, configure it in `.entire/settings.local.json` so it is always used: ```bash theme={null} entire configure --local --checkpoint-remote github:owner/repo ``` ## Push Behavior When you push code, Entire pushes checkpoint data to the checkpoint repository separately, using the same protocol, SSH or HTTPS, as your Git remote. The checkpoint repository is used regardless of which of your remotes would otherwise receive checkpoints. If the checkpoint repository cannot be reached, your main Git push still succeeds. Entire keeps the checkpoint data locally and warns that it could not sync. With the legacy branch storage backend, Entire also fetches existing checkpoint data from the checkpoint repository once, if it has data you don't. The default `git-refs` backend fetches checkpoints on demand instead. ## Use a Separate Token Set `ENTIRE_CHECKPOINT_TOKEN` to authenticate checkpoint fetches and pushes with a dedicated token, without changing the credentials for your code repository. When it is set, Entire: * Adds the token to the HTTPS Git operations it runs for checkpoints. * Rewrites SSH remotes, including `origin`, to the equivalent HTTPS URL for checkpoint operations, so the token can authenticate. If a URL cannot be rewritten, the operation runs over SSH without the token and Entire prints a warning. * Without a `checkpoint_remote`, applies the token to the remote chosen as described in [Choose Where Checkpoints Are Uploaded](/guides/checkpoints/checkpoint-destination). ```bash theme={null} ENTIRE_CHECKPOINT_TOKEN= git push ``` # Review and Require Checks Source: https://docs.entire.com/guides/ci/checks Review CI results in plugin gates and choose which builds must pass before merging. To see the CI results for a change, open its Trail. Each vendor reports a **check suite** for a workflow or build. Depot also reports **check runs** for individual jobs; Buildkite does not report step details yet. For repositories that use a CI plugin, results appear in the plugin's own line under **Gates**. This applies to both repositories hosted on Entire and repositories mirrored from GitHub. The separate **Checks** gate is available only on GitHub mirrors. The suite reports the overall outcome. It can remain pending after some jobs pass because the vendor still has work to finish. Open the vendor's build details, when available, to read logs and investigate failures. ## Require Checks Before Merging For both Buildkite and Depot, any failed plugin build blocks merging by default when **Required checks** is empty. A build that has not reported any results does not block merging in this configuration. Populate the field only if you want to block on specific build types: 1. Open the repository in entire.com and go to **Settings** then **Gates**. 2. Find the gate for your CI plugin. 3. To block only on specific build types, set **Required checks** using the names described below. [Configure the Checks gate and required checks](https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/02219a4c9f9e53e95ea9a71000ab4d48/iframe) ### Buildkite Name the pipeline in `org/pipeline` format. For example, to require the `tests` pipeline in the `acme` organization, enter `acme/tests`. ### Depot Copy the full check name shown on the Trail for the workflow or individual job you want to require. For example, the job in the screenshot below is reported as `push:ci.yml / ci.yml:checks`. Enter that full name in **Required checks**; entering only `checks` will not match. ![Depot CI plugin gate on an Entire-hosted repository's Trail showing one of one checks passed](https://mintcdn.com/entire/mLuNv5SexCtqUE8w/images/ci-depot-plugin-trail.png?fit=max\&auto=format\&n=mLuNv5SexCtqUE8w\&q=85\&s=1a8159375c1418af17e09283b45aae03) Depot plugin on Trails, showing the Depot CI gate with its reported job passed. Names must match the builds your plugin reports. If you rename a pipeline, workflow, or job, update its required name in the plugin's gate too. ### GitHub Mirrors A GitHub mirror can also use the **Checks** gate to require checks reported through GitHub. This gate is separate from the gates for installed CI plugins and is not available on repositories hosted directly on Entire. ![Expanded Checks gate on a GitHub mirror Trail showing nine passed GitHub checks](https://mintcdn.com/entire/mLuNv5SexCtqUE8w/images/ci-github-mirror-checks.png?fit=max\&auto=format\&n=mLuNv5SexCtqUE8w\&q=85\&s=a1ff5e0d6f61e302e8540606ef1be26c) GitHub checks on a GitHub mirror Trail, with all nine checks passed. The Checks gate reads checks from GitHub but doesn't use GitHub's branch protection rules. Name the checks you need in that gate. A named check that hasn't been reported fails once all other checks have finished, or earlier if another reported check fails while others are still running. If you select **Require all checks to succeed**, every reported GitHub check must also pass. ## Understand the Result Review the plugin's gate on the Trail to see whether its required builds have completed. Individual jobs can finish while the overall workflow or build is still running. Entire evaluates requirements against the latest commit. A passing result from an earlier commit does not satisfy the requirement for a newer change. When a plugin has names configured in **Required checks**, missing checks normally block merging. The exception is when Entire knows that the commit was pushed before the plugin was connected, those checks appear as **Not reported** and do not block merging. If a required result is missing or pending, compare the Trail's latest commit with the vendor's build and confirm that the configured name matches the pipeline, workflow, or job that reports it. All blocking gates must pass before you can merge, unless someone with bypass permission bypasses them. # Connect a CI Vendor Source: https://docs.entire.com/guides/ci/connect-ci Install a CI plugin on an Entire project and choose which repositories it can access. Start in Entire to connect your CI vendor. You need permission to manage the Entire project where you want to install the plugin. ## Install the Plugin 1. Go to **Projects**, select the project in which you want to enable plugins, then click on **Plugins**. 2. Choose the vendor plugin you want to add and click **Install**. You will be routed to the vendor's site ([Buildkite](https://buildkite.com/organizations/~/repository-providers) or [Depot](https://depot.dev/orgs/_/settings/ci/general)) to complete its connection steps. 3. Then you will need to select the project and under that the repositories the plugin can access. Click **Install** to complete the plugin installation. [Select a project and repositories to install the CI plugin](https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/0b4f673c572b73c75f39d7ba1c9a9662/iframe) 4. Finish configuring the pipeline or workflow in your vendor's product, including the build commands and push triggers for your connected repositories. 5. Now whenever you push a change, the CI vendor you conifgured, runs the build and reports its results, you will see them in the plugin's line under **Gates** on the Trail. This applies to both repositories hosted on Entire and GitHub mirrors. ## Remove Access You can remove a repository from the plugin installation in Entire or uninstall the plugin from the project. Removing a repository revokes the plugin's access to that repository while uninstalling revokes access for the whole installation. Review the plugin's gate under **Settings** and then **Gates** when you remove an installation. Update or remove requirements for builds that can no longer report results. # Overview Source: https://docs.entire.com/guides/ci/overview Run builds and tests with Buildkite or Depot, review results, and require checks before merging on Entire. ## What Is Entire CI Integrations? Entire CI Integrations connects your Git repository to CI providers like Buildkite and Depot so you can run builds and tests whenever you push a change. You connect a provider through a plugin and use your configured pipelines to check your code. Entire collects the results so you can see which checks passed or failed and require them to pass before merging. Entire CI Integrations is currently available in public preview with Buildkite (hosted agents) and Depot, with more providers coming soon. Your build commands and pipeline configurations stay with your CI provider. [CI on Entire: Connect Depot and Buildkite to Your Trails](https://www.youtube.com/embed/n6FOObeyQpk) ## How Does It Help? Entire CI Integrations helps you catch issues before merging changes. You can check whether your code builds successfully, see which tests passed or failed, and make sure important checks are completed before a change is merged. For example, if you update an authentication flow, your CI provider can run the tests configured for that repository. Entire shows the results on the Trail alongside your changes. If a test fails, you can open the build details in your CI provider to investigate. You can also configure **Required checks** to prevent changes from merging until the selected checks pass. ## How Does It Work? Once you connect a CI provider to Entire, the process works as follows: 1. You push a change to a connected repository. 2. Entire notifies your CI provider about the change. 3. The provider fetches your code and runs the configured builds and tests. 4. The provider sends the results back to Entire, where you can review them on Entire Trails. ## Connect a CI Provider You can connect Buildkite or Depot to Entire by installing the provider's plugin. Start the setup from your project's **Plugins** page in entire.com. Click **Install** to go to the vendor's site, complete the vendor's connection steps, then return to Entire to grant consent and select repositories. You can give the plugin access to all repositories in a project or only specific ones. Finish the vendor's pipeline or workflow setup so pushes can trigger builds. ![Project Plugins page in entire.io showing Buildkite and Depot CI plugins, with Plugins highlighted in the sidebar](https://mintcdn.com/entire/0-1LEbalzQ0bymcb/images/ci-plugins.png?fit=max\&auto=format\&n=0-1LEbalzQ0bymcb\&q=85\&s=a2d61e74750ff6a146e6a6b81ade79b7) The plugin allows Entire to notify the provider about new changes and also allows the provider to fetch code and report build results. See [Connect a CI Vendor](/guides/ci/connect-ci) to get started. ## Review Results and Require Checks Once your CI provider runs a pipeline, Entire displays the results in the plugin's line under **Gates** on the Trail. Plugin gates are available on both repositories hosted on Entire and GitHub mirrors. The separate **Checks** gate is available only on GitHub mirrors. You can see whether each check passed, failed, or is still running. If a check fails, you can open the build in your CI provider to find out what went wrong. You can also set up **Required checks** for each plugin under the repository's **Settings** then **Gates**. For Buildkite, name the pipeline in `org/pipeline` format. For Depot, copy the full check name shown on the Trail, such as `push:ci.yml / ci.yml:checks`; entering only `checks` will not match. Required builds normally block merging until they pass, with an exception for [commits pushed before the plugin was connected](/guides/ci/checks#understand-the-result). Entire evaluates the required checks against the latest commit. This means a passing result from an earlier commit cannot be used to merge a newer change. See [Review and Require Checks](/guides/ci/checks) to learn more. ## Continue With > **[Connect a CI Vendor](/guides/ci/connect-ci)** > > Install a plugin and choose its repositories. > **[Review and Require Checks](/guides/ci/checks)** > > Review build results and configure merge requirements. > **[Troubleshooting](/guides/ci/troubleshooting)** > > Investigate missing checks and blocked merges. # Troubleshoot CI Source: https://docs.entire.com/guides/ci/troubleshooting Find out why a build has not started, checks are missing, or a Trail cannot merge. ## The Build Does Not Start If the build does not start, first confirm that the plugin is installed in the repository. Then check that you finished the vendor's pipeline setup and that the push matches its build triggers. Start the connection from the project's **Plugins** page in Entire if you have not installed the vendor's plugin yet. See [Connect a CI Vendor](/guides/ci/connect-ci). ## Buildkite Checkout Fails If checkout fails with `'remote-entire' is not a git command`, check if **Add the Entire plugin to every job** is off on the Entire connection in Buildkite. Open that connection and turn the setting back on. It is on by default. ## The Build Finishes, but Checks Stay Pending Compare the build's commit with the Trail's latest commit. A result from an earlier commit does not satisfy the current requirement. Check the overall workflow status in the vendor's product. Individual jobs can finish while the suite remains pending. If the build has finished but the suite has not updated, you will need to report the mismatch to the vendor with the repository, commit, and build link. ## The Plugin Gates Do Not Block Merges Open **Settings** then **Gates** and find the gate for your CI plugin. For both Buildkite and Depot, any failed plugin build blocks merging when **Required checks** is empty. A build that has not reported any results does not block merging in this configuration. Populate the field only to [block on specific build types](/guides/ci/checks#require-checks-before-merging). When names are configured in **Required checks**, missing checks normally block merging. If Entire knows that the commit was pushed before the plugin was connected, those checks appear as **Not reported** and do not block merging. Plugin gates are available on both repositories hosted on Entire and GitHub mirrors. The separate **Checks** gate is available only on GitHub mirrors and controls checks reported through GitHub. ## A Required Check Never Reports Check the required name in the plugin's gate against the build your vendor reports: * For Buildkite, use the pipeline name in `org/pipeline` format, such as `acme/tests`. * For Depot, copy the full check name shown on the Trail, such as `push:ci.yml / ci.yml:checks`. Entering only the job name, `checks`, will not match. If you rename a pipeline, workflow, or job, update the required name too. If you removed or reinstalled the plugin, review its gate configuration under **Settings → Gates**. Remove requirements for builds you no longer run, or update the plugin's **Required checks** to match the builds you need. # Entire-Generated Files Source: https://docs.entire.com/guides/configuration/entire-files Decide which Entire-generated files belong in Git and which should stay on your machine. Entire creates a small set of repository files for configuration, redaction rules, diagnostics, and local runtime state. Commit files that define shared project behavior. Keep personal overrides, logs, temporary files, and machine-local state out of Git. ## Commit or Keep Local | Path | Commit? | Use for | | - | - | - | | `.entire/settings.json` | Yes, when Entire is part of the project | Shared project settings, such as checkpoint storage, team redaction rules, and default repository behavior | | `.entire/.gitignore` | Yes | Keeping local Entire files out of normal commits | | `.entire/redactors/` | Yes, for shared rule packs | Team redaction rules that should apply to everyone working in the repository | | `.entire/settings.local.json` | No | Personal overrides, debug logging, private rules, and machine-specific settings | | `.entire/redactors/local/` | No | Personal redaction rule packs | | `.entire/logs/` | No | Local diagnostic logs | | `.entire/tmp/` | No | Temporary runtime files | | `.entire/metadata/` | No | Local metadata generated while Entire runs | | `.entire/current_session` | No | Pointer to your current local session | If you are trying Entire locally before adopting it for the project, keep `.entire/settings.json` local until the team decides to share Entire configuration. ## Files Stored Elsewhere Checkpoint data is not committed from your working tree. Entire stores checkpoint metadata in Git refs under `refs/entire/checkpoints/`, or on the `entire/checkpoints/v1` branch for repositories on the branch backend, in your code repository or in a configured checkpoint remote. See [Where your data lives](/security#where-your-data-lives). Global settings live at `~/.config/entire/settings.json`. Agent hook files live in agent-specific folders, such as `.agents/`, `.claude/`, `.codex/`, and `.cursor/`. # Git Hooks Source: https://docs.entire.com/guides/configuration/git-hooks Configure the Git hooks Entire uses to capture and sync checkpoint data. Use this page when `git commit` or `git push` is not creating, linking, or syncing checkpoint data. Entire uses Git hooks to run during normal Git commands: * `git commit` links captured agent work to the commit and creates an `Entire-Checkpoint` trailer. * `git push` syncs checkpoint data after your code push. If those behaviors do not happen, Git may not be running Entire's hooks, or the hook may not be able to find the `entire` command. ## Start Here If * a commit did not create a checkpoint * a commit is missing an `Entire-Checkpoint` trailer * checkpoint data is not syncing after `git push` * commits work from Terminal, but not from a GUI Git client * Git says it cannot find the `entire` command * hooks were removed, overwritten, or need to be reinstalled * the `entire` binary moved on your machine * setup needs to run without prompts * the repository already has Git hooks, or uses a hook manager such as lefthook or pre-commit > [!NOTE] > > Git hooks are different from [agent hooks](/agents/setup). > Agent hooks capture the AI session while you work; Git hooks connect that > captured session to commits and pushes. ## Install Git Hooks For a new repository, run `entire enable` to install the Git hooks Entire needs for commit and push behavior: ```bash theme={null} entire enable ``` ## Reinstall Git Hooks If hooks were removed, overwritten, or stopped running, reinstall them with: ```bash theme={null} entire configure --force ``` ## Keep Your Existing Git Hooks If the repository already has Git hooks, such as your own scripts or hooks from git-lfs, lefthook, or pre-commit, `entire enable` keeps them. Each one is moved to `.pre-entire` in the hooks directory, and Entire's hook runs first, then yours. * If a hook manager reinstalls its hooks later, Entire's hooks come back on the next agent turn or `entire enable`, chained to the hook manager's version. If the hook already had a `.pre-entire` copy, the hook manager's version takes its place and runs after Entire's; the older copy is kept as `.pre-entire.` and no longer runs, with a warning naming the file. * `entire disable --uninstall` removes Entire's hooks and puts yours back. Older `.pre-entire.` copies are left in place and listed. ## GUI Git Clients Terminal commits can work while GUI commits fail because apps like Xcode, Tower, GitKraken, and Sourcetree may not load your shell `$PATH`. Configure hooks with the full `entire` binary path: ```bash theme={null} entire configure --local --absolute-git-hook-path ``` During initial setup, use the same option with `entire enable`: ```bash theme={null} entire enable --local --absolute-git-hook-path ``` This embeds the full path to the `entire` binary directly in the Git hooks: ```sh theme={null} # Default entire hooks git post-commit # With --absolute-git-hook-path '/Users/you/go/bin/entire' hooks git post-commit ``` The setting is written to `.entire/settings.local.json` when you pass `--local`: ```json .entire/settings.local.json theme={null} { "absolute_git_hook_path": true } ``` Absolute Git hook paths are machine-specific. If you move the `entire` binary, rerun: ```bash theme={null} entire configure --local --absolute-git-hook-path ``` ## Use Non-Interactive Setup For scripts, CI, or bootstrap flows, run setup in non-interactive mode: ```bash theme={null} entire enable --yes ``` To select an agent without prompts: ```bash theme={null} entire enable --yes --agent claude-code ``` ## Verify Git Hooks After changing hook setup, check the repository status and test the Git client you actually use: ```bash theme={null} entire status --detailed ``` Then make a test commit and push. If no checkpoint appears, run [checkpoint troubleshooting](/guides/sessions/troubleshooting). # Logging and Diagnostics Source: https://docs.entire.com/guides/configuration/logging-and-diagnostics Configure log verbosity, inspect active settings, and collect diagnostics. Use this page when you need more detail about what Entire is doing locally or need to confirm which settings are active. Most diagnostic output is local to your machine. Turn on debug logging temporarily unless the whole team needs the same verbosity. ## Start Here If Use this page to: * turn on debug logging while investigating an issue * confirm which settings Entire is using * run a repository health check * view logs or create a diagnostic bundle ## Log Level `log_level` controls how much detail Entire writes to operational logs. The default is `info`; use `debug` while investigating. **Temporary Override** Use `ENTIRE_LOG_LEVEL` when you need debug output for one command or one shell session. ```bash theme={null} ENTIRE_LOG_LEVEL=debug entire status ``` `ENTIRE_LOG_LEVEL` takes precedence over settings files. **Local Settings** Use local settings for temporary debug logging or machine-specific troubleshooting. ```json .entire/settings.local.json theme={null} { "log_level": "debug" } ``` **Project Settings** Use project settings only when the whole repository should use the same log level. ```json .entire/settings.json theme={null} { "log_level": "debug" } ``` Supported values are `debug`, `info`, `warn`, and `error`. ## Inspect Active Settings Run: ```bash theme={null} entire status --detailed ``` Use this after editing settings to confirm Entire is reading the value you changed and to see which settings file supplied it. ## Check Repository Health Run: ```bash theme={null} entire doctor ``` Use `entire doctor` when sessions look stuck, Git hooks are not firing, checkpoint data is not syncing, or `entire status` shows warnings. It checks repository setup, hook state, checkpoint metadata, and common session problems. ## View or Share Diagnostics Entire writes local diagnostic logs under `.entire/logs/`. Keep logs local unless someone asks for a specific file or bundle while troubleshooting. **View Logs** Show recent operational logs with: ```bash theme={null} entire doctor logs ``` To stream new log lines while you reproduce an issue, run: ```bash theme={null} entire doctor logs --follow ``` **Create Bundle** Create a diagnostic bundle for an issue report with: ```bash theme={null} entire doctor bundle ``` Diagnostic bundles are redacted by default. Use `--raw` only when support has asked for an unredacted bundle. For other local runtime files under `.entire/`, see [Entire-Generated Files](/guides/configuration/entire-files). ## Trace Slow Hooks Hooks that take 1.5 seconds or longer trace themselves by default, at WARN level, so a slow hook records its own breakdown with no configuration. Reproduce the slow Git command, then run: ```bash theme={null} entire doctor trace ``` Use this when `git commit` or `git push` works but feels slower than expected. Set `ENTIRE_PERF_SLOW_MS=0` to turn automatic tracing off. A [log level](#log-level) above WARN also hides these traces. To trace every hook, including fast ones, set the log level to `debug`. See [`entire doctor trace`](/cli-reference/doctor#doctor-trace) for `--summary`, `--slow`, and the other flags. ## Verify Logging Changes After changing logging settings, rerun the command you were investigating and check the logs: ```bash theme={null} entire doctor logs ``` # Configuration Source: https://docs.entire.com/guides/configuration/overview Find the right place to configure Entire. Use configuration docs when you need to change how Entire behaves in a repository, on your machine, or during Git and agent workflows. Use the table below to find the guide for the part of Entire you want to configure. ## What Are You Configuring? | If you want to configure... | Go to | | - | - | | Repository namespaces, regions, and member access | [Projects](/guides/configuration/projects) | | Local, project, or global settings files | [Local, Project, and Global Settings](/guides/configuration/settings-layers) | | Which Entire-generated files should be committed or kept local | [Entire-Generated Files](/guides/configuration/entire-files) | | Where checkpoint data is stored or pushed | [Session Storage](/guides/checkpoints/checkpoint-storage) | | Git commit and push hooks, including GUI Git clients | [Git Hooks](/guides/configuration/git-hooks) | | Antigravity CLI, Claude Code, Codex, Copilot CLI, Cursor, Factory, OpenCode, Pi, or custom agent integration hooks | [Set Up an Agent](/agents/setup) | | Redaction rules, PII, telemetry, or checkpoint commit signing | [Privacy and Redaction](/guides/configuration/privacy-and-redaction) | | Debug logs, diagnostics, or effective settings | [Logging and Diagnostics](/guides/configuration/logging-and-diagnostics) | | Saved review profiles for `entire review` | [Review Profiles](/guides/configuration/review-profiles) | ## How Configuration Is Layered Entire merges settings from multiple places. More specific settings win: 1. Local settings: `.entire/settings.local.json` 2. Project settings: `.entire/settings.json` 3. Global settings: `~/.config/entire/settings.json` 4. Defaults Use project settings for behavior the whole team should share. Use local settings for personal preferences, machine-specific setup, debug logging, or private redaction rules. ## Common Paths > **[Local, Project, and Global Settings](/guides/configuration/settings-layers)** > > Choose local, project, or global settings for a configuration change. > **[Entire-Generated Files](/guides/configuration/entire-files)** > > Decide which Entire-generated files belong in Git and which should stay local. > **[Session Storage](/guides/checkpoints/checkpoint-storage)** > > See which storage backend a repository uses, switch backends, and migrate. > **[Fix GUI Git Commits](/guides/configuration/git-hooks)** > > Use absolute Git hook paths when GUI clients cannot find the Entire binary. > **[Control Privacy Settings](/guides/configuration/privacy-and-redaction)** > > Configure redaction, telemetry, and checkpoint commit signing. # Privacy and Redaction Source: https://docs.entire.com/guides/configuration/privacy-and-redaction Configure redaction layers, image externalization, telemetry, and checkpoint commit signing. Use this page to configure privacy-related behavior for a repository or for your local machine. By default, Entire redacts API keys, access tokens, credentialed URLs, database connection strings, and private keys before it writes checkpoint metadata. Secret scanning remains active, but you can choose which pattern scanner Entire uses. For the threat model, the full list of redaction layers, and what each layer does and does not cover, see [Security & Privacy](/security). ## Start Here If Use this page to: * choose secret scanner engines * add PII or custom redaction rules * turn on the OpenAI Privacy Filter * move inline images out of transcripts * opt in or out of anonymous CLI analytics * change checkpoint commit signing ## Settings Reference Every key below lives under `.entire/settings.json` (shared with the team) or `.entire/settings.local.json` (yours alone), except where noted. | Setting path | Type | Default | Effect | | - | - | - | - | | `redaction.betterleaks.enabled` | boolean | `true` | Run Betterleaks for secret pattern matching. **Project settings only** | | `redaction.goredact.enabled` | boolean | `false` | Run goredact for secret pattern matching. **Project settings only** | | `redaction.pii.enabled` | boolean | `false` | Turn on [PII redaction](#pii-redaction) | | `redaction.pii.email` | boolean | `true` when PII is on | Redact email addresses | | `redaction.pii.phone` | boolean | `true` when PII is on | Redact phone numbers | | `redaction.pii.address` | boolean | `false` | Redact US street addresses | | `redaction.pii.custom_patterns` | object | `{}` | Label-to-regex map producing `[REDACTED_