cli README

The project's README from github.com/entireio/cli. As one markdown file: README.md.

Entire CLI

Entire hooks into your Git workflow to capture AI agent sessions as you work. Sessions are indexed alongside commits, creating a searchable record of how code was written in your repo.

With Entire, you can:

Why Entire

Table of Contents

Requirements

Quick Start

macOS and Linux

Install with Homebrew:

brew tap entireio/tap
brew trust entireio/tap
brew install --cask entire            # stable
# brew install --cask entire@nightly  # or nightly

Or with the install script:

curl -fsSL https://entire.io/install.sh | bash                          # stable
# curl -fsSL https://entire.io/install.sh | bash -s -- --channel nightly  # or nightly

Windows

Install with Windows PowerShell 5.1 or later:

irm https://entire.io/install.ps1 | iex  # stable
# or nightly:
# iex "& {$(irm https://entire.io/install.ps1)} -Channel nightly"

For stable releases, the PowerShell installer uses Scoop when it is available, adding the Entire bucket if needed. Without Scoop — and for nightly releases — it verifies the release checksum and installs both entire.exe and git-remote-entire.exe to %USERPROFILE%\.local\bin, adding that directory to your user PATH if needed.

Or install the stable release with Scoop:

scoop bucket add entire https://github.com/entireio/scoop-bucket.git
scoop install entire/entire

Migrating an old cli Scoop install (package rename)

The Scoop package was renamed from cli to entire. If your install is still registered as the old cli package, run the migration below. It installs the new package before removing the old one, so the old install is only removed once the new one is in place (scoop reset re-links the shared entire.exe and git-remote-entire.exe shims). Run it where entire is not running — a live entire.exe locks its own shim, so Scoop can't relink or uninstall it mid-run:

cmd.exe /D /C "scoop install entire/entire && scoop uninstall entire/cli && scoop reset entire"

If the first step fails with "couldn't find manifest", your bucket clone predates the renamed package — run scoop update to refresh it, then retry the command above. Nothing is removed until the install succeeds, so a failed attempt leaves your existing install working.

Go (development/manual setup)

go install github.com/entireio/cli/cmd/entire@latest

# The git remote helper that resolves entire:// URLs, needed for `entire repo clone`
# and `git clone entire://…`. The packaged installs above bundle it.
go install github.com/entireio/cli/cmd/git-remote-entire@latest

# Add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc if not already configured)
export PATH="$HOME/go/bin:$PATH"

Install both, or just entire if you never clone over entire://. Git finds the helper by name on $PATH, which is what go install produces, so nothing else needs configuring.

One difference from a stable release: a go install build leaves experimental commands visible in entire help, the same as a nightly or a local build.

Enable in your project

cd your-project && entire enable

# Check status
entire status

After the initial setup, use entire agent to add or remove agents, entire configure to update non-agent settings, and entire enable / entire disable to toggle Entire on or off.

Release Channels

Entire currently ships two release channels:

How to use each channel:

Typical Workflow

1. Enable Entire in Your Repository

entire enable

On a repo that has not been enabled yet, entire enable runs the initial enable flow: it creates Entire settings, installs git hooks, and prompts you to choose which agent hooks to install. To enable a specific agent non-interactively, use entire enable --agent <name> (for example, entire enable --agent cursor).

After setup:

The hooks capture session data as you work. Checkpoints are created when you or the agent make a git commit. Your code commits stay clean, Entire never creates commits on your active branch. Session metadata is stored outside your branch's history, in the checkpoint storage described under Checkpoint Storage.

2. Work with Your AI Agent

Just use one of your AI agents as before. Entire runs in the background, tracking your session:

entire status  # Check current session status anytime

3. Resume a Previous Session

To restore the latest checkpointed session metadata for a branch:

entire session resume <branch>

Entire checks out the branch, restores the latest checkpointed session metadata (one or more sessions), and prints command(s) to continue.

4. Disable Entire (Optional)

entire disable

Removes the git hooks. Your code and commit history remain untouched.

Key Concepts

Sessions

A session represents a complete interaction with your AI agent, from start to finish. Each session captures all prompts, responses, files modified, and timestamps.

The session ID is the unique identifier the agent itself provides — Entire never mints its own — so an ID you see in entire session list is the same one the agent uses. The format is the agent's to choose: most supply a UUID (e.g. 019efea2-b46a-7cbc-be01-4c13460f5019), while OpenCode uses ses_-prefixed IDs.

Sessions are stored separately from your code commits, in the repo's checkpoint storage.

Checkpoints

A checkpoint is a snapshot within a session—a "save point" in your work.

Checkpoints are created when you or the agent make a git commit, and the commit carries an Entire-Checkpoint: <id> trailer linking the two.

Checkpoint IDs are 26-character ULIDs (e.g. 01K9TQ8ZP7X3F5M2WVJ4CNRB6D), which sort by creation time. Checkpoints written by older versions of Entire carry a legacy 12-character hex ID (e.g. a3b2c4d5e6f7); both formats stay readable in the same repo, and you can pass either to any command that takes a checkpoint ID.

Checkpoint Storage

Checkpoints live in your repository's own git object store, never in your branch's history. Each checkpoint is its own git ref:

refs/entire/checkpoints/<shard>/<id>

The ref points at a commit whose tree is that checkpoint — metadata.json, the per-session transcript files, and any subagent task records. <shard> is the last two characters of the ID, which keeps the refs evenly distributed.

Because checkpoints are independent refs, they are written, pushed, and fetched independently. There is no shared branch tip for concurrent sessions to contend on, and a reader can fetch exactly the one checkpoint it needs instead of a whole history. A checkpoint written on another machine is fetched on demand the first time you read it.

entire enable sets this up; there is nothing to configure. It is recorded in .entire/settings.json as:

{
  "checkpoints": {
    "primary": { "type": "git-refs" }
  }
}

Inspect what a repo has locally with plain git, or through Entire:

git for-each-ref refs/entire/checkpoints    # the raw refs
entire checkpoint list                      # checkpoints on this branch
entire checkpoint explain <id>              # one checkpoint in full

How It Works

Your Branch                      Checkpoint storage
     │                                  │
     ▼                                  │
[Base Commit]                           │
     │                                  │
     │  ┌─── Agent works ───┐           │
     │  │  Turn 1           │           │
     │  │  Turn 2           │           │
     │  │  Turn 3           │           │
     │  └───────────────────┘           │
     │                                  │
     ▼                                  ▼
[Your Commit] ─────────────────► [Checkpoint]
  Entire-Checkpoint: <id>          (transcript, prompts,
     │                              files touched, tokens)
     ▼

Work in progress is held on a short-lived shadow branch as you go. When you commit, that work is condensed into a permanent checkpoint and linked to your commit by an Entire-Checkpoint trailer.

Strategy

Entire uses a manual-commit strategy that keeps your git history clean:

Git Worktrees

Entire works seamlessly with git worktrees. Each worktree has independent session tracking, so you can run multiple AI sessions in different worktrees without conflicts.

Concurrent Sessions

Multiple AI sessions can run on the same commit. If you start a second session while another has uncommitted work, Entire warns you and tracks them separately. Both sessions' checkpoints are preserved, and a commit condenses every session with pending work in that worktree.

Headless & CI Authentication

By default entire login opens a browser to sign in and stores tokens in the OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager). Machines without a usable browser or keyring — headless servers, containers, minimal VMs, CI runners — have two supported paths:

Interactive login on a headless machine

Sign-in itself already handles this: with no interactive terminal, or over SSH, entire login switches to the device-code flow on its own and prints an approval URL you can open on any machine. entire login --device forces that flow explicitly. Only token storage needs an override — use the file-backed store:

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 persistently (e.g. in your shell profile) so later commands read from the same store.

Non-interactive automation (CI, workload identity)

Skip login and storage entirely by injecting a token per invocation:

ENTIRE_TOKEN=<login-or-sa-session-JWT> entire ...

ENTIRE_TOKEN bypasses stored credentials; the CLI derives the control-plane endpoint from the token itself. Nothing is written to disk. This is the right path for CI pipelines and service accounts.

Seeing save login / failed to unlock correct collection errors from entire login? That's the OS keyring being unavailable — use one of the two paths above.

Commands Reference

Descriptions below are the commands' own summaries. entire help always reflects the installed binary; entire agent-help is the machine-readable version agents read.

Setup

Command Description
entire enable Enable Entire in current repository
entire disable Disable Entire in current repository
entire status Show Entire status (--json for structured output)
entire agent Manage agent integrations (add, remove, list)
entire configure Update non-agent Entire settings in the current repository
entire doctor Diagnose and fix session issues (trace, logs, bundle, migrate-checkpoints)
entire clean Clean up Entire session data (--all for repo-wide cleanup)
entire plugin Manage Entire plugins (see Plugins)

Sessions & Checkpoints

Command Description
entire session Manage agent sessions (list, info, current, stop, attach, adopt, resume, tokens)
entire session resume Resume a stopped session — interactive picker, or by branch
entire checkpoint Inspect and search checkpoints (list, explain, tokens, search)
entire checkpoint explain Explain a checkpoint, commit, or session
entire search Search checkpoints, commits, and sessions using semantic and keyword matching
entire activity Show your activity overview
entire recap Summarize recent checkpoint activity
entire dispatch Generate a dispatch summarizing recent agent work

Account

Command Description
entire login Log in to Entire (browser by default; --device for the device-code flow)
entire logout Log out of Entire
entire auth Manage authentication (status, contexts, use, token, login, logout)

Control Plane

Command Description
entire org Manage Entire organizations (create, list, get, delete)
entire project Manage Entire projects (create, list, get, delete)
entire repo Manage Entire repositories (create, list, get, delete, clone, mirror, visibility)
entire grant Manage Entire access grants and org membership (org, project, repo)
entire api Make an authenticated request to an Entire API and print the response

Other

Command Description
entire agent-help Machine-readable usage for coding agents (always matches the installed CLI)
entire labs Explore experimental Entire workflows
entire version Show build information

Experimental Commands

These are visible in developer and nightly builds and hidden in stable releases, but always runnable in every build. Run entire labs to discover them.

Command Description
entire review Run a multi-agent review against a branch
entire investigate Run a multi-agent investigation against the current branch
entire tokens Analyze token usage across sessions and checkpoints
entire blame Show which lines came from Entire checkpoints
entire why Show why a line exists
entire experts Rank agent provenance for code scopes
entire import Import pre-existing agent history into Entire
entire runner Set up and tune trail runners for this repository

entire blame <file> shows which current file lines came from an Entire checkpoint (--long for the full agent, model, author, and session table), and entire why <file>:<line> jumps from a specific line back to the prompt, session, and checkpoint that created it.

entire enable Flags

Flag Description
`--agent <name

cli (entireio/cli)

Searching Database…

5.2K ·GitHub
Cli
这是什么？Entire 是一个命令行工具，它挂接到你的 Git 工作流中，记录 AI 编码代理的会话（提示词、回复、涉及的文件），并将这些内容与你的提交一同建立索引，形成一份可搜索的记录，展示代码是如何编写的。
这是图形界面应用，还是在后台静默运行？它是一个命令行工具，会在你的仓库中安装 Git 钩子。你使用 AI 代理时它在后台运行，你只需通过 entire session 或 entire search 等命令直接与它交互。
我该怎样安装，并在项目上开始使用？在 macOS 或 Linux 上，可通过 Homebrew（brew install --cask entire）或安装脚本安装；在 Windows 上使用 PowerShell 安装程序（可用时会使用 Scoop）。然后在你的仓库中运行 entire enable，以安装 Git 钩子，并选择要添加的代理集成。
使用它之前需要准备什么？支持哪些代理？你需要安装并完成身份验证的 Git 和受支持的 AI 代理，文中提到的有 Claude Code、Codex、Gemini、Cursor、Pi 和 OpenCode。若要使用 go install 从源码构建，还需要 Go 1.26+。
Entire 会改动我的提交历史吗？CI 或无头机器上怎么办？不会——Entire 从不在你当前的分支上创建提交；检查点存储为独立的 Git 引用，位于分支历史之外。在没有可用浏览器或操作系统密钥环的无头机器上（如 CI、容器、精简虚拟机），你需要使用设备代码登录流程，或基于文件或令牌的登录方式，而不能使用默认的密钥环。
我的会话数据和登录令牌究竟存放在哪里？会话记录和检查点以独立引用的形式存储在你自己仓库的 Git 对象库中，从不写入分支历史；登录令牌默认存放在操作系统密钥环中（macOS 钥匙串、Linux Secret Service、Windows 凭据管理器），在无头环境中则存放在本地的 tokens.json 文件里。
会话和检查点有什么区别？会话是你与 AI 代理从开始到结束的完整交互，记录所有提示词、回复和涉及的文件；检查点则是你或代理每次执行 git commit 时所做的快照，并通过 Entire-Checkpoint 尾注与该提交关联。
如何恢复之前的 AI 会话？运行 entire session resume（可交互式操作，也可按分支指定）。Entire 会切换到对应分支，恢复最新的检查点会话元数据，并输出继续命令，让你从上次中断的地方接着进行。
它能否与 git worktree 以及多个并发的代理会话一起使用？可以——每个工作树都有独立的会话跟踪；如果多个 AI 会话在同一个提交上运行，Entire 会分别跟踪它们，并保留各自的所有检查点。
有哪些发布渠道？Entire 提供 “stable” 渠道，这是 Homebrew、Scoop 和 install.sh 的默认渠道；另外还有更新更频繁的 “nightly” 渠道，供希望更早获得最新改动的用户使用。
What are similar projects?iFixAi, casbin-gateway, gh-aw, overmind, golutra, destructive_command_guard, OpenAPPA, copperhead
Which topics is it in?agent-observability, developer, audit, compliance, agent-tools, version-control, oauth2, ci, git, cursor, gemini, agents
Creator
entireio
Size
727.8 MB
Stars
5.2K
Updated
CommitOct 16Releasev0.11.5Oct 14
Age
9mo
Commits · 90 Days