> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# trail

> Create, review, and merge trails across repositories and branches.

Manage [trails](https://docs.entire.com/glossary.md#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`](https://docs.entire.com/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 `<repo>/<number>`.

Commands that take a `<trail>` argument accept these selectors:

| Selector | Meaning |
| - | - |
| `12` | A project trail by its project-wide number. |
| A ULID | A project trail by its ID. |
| `<repo>/<number>` | 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/<owner>` or `et/<project>`. Required for `list`. Otherwise defaults to the current repository's namespace: `gh/<owner>` for a GitHub mirror, `et/<project>` 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 [<trail>] [flags]
```

Pass a project trail number or ID, or a `<repo>/<number>` 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 [<trail>] [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 <trail> [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 [<trail>] [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 `<repo>/<number>` 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 [<trail>] [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 `<repo>/<number>`. 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 `<repo>/<number>`. 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 [<trail>] [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 `<repo>/<number>`. 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 [<trail>] [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. |
| `<event_type>` | 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 `<repo>/<number>`. 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 <discussion-id> [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 <discussion-id> -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 <discussion-id> <message-id> -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 <discussion-id> <message-id> [flags]
```

| Flag | Description |
| - | - |
| `-f, --force` | Confirm the deletion. |

### trail comment resolve

Resolve a discussion.

```bash theme={null}
entire trail comment resolve <discussion-id> [flags]
```

### trail comment unresolve

Reopen a resolved discussion.

```bash theme={null}
entire trail comment unresolve <discussion-id> [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 [<trail>] [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 [<trail>] [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 [<trail>] [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 `<repo>/<number>` 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](https://docs.entire.com/guides/trails/gates.md) 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 [<trail>] [flags]
entire trail finding SUBCOMMAND [flags]
```

A [finding](https://docs.entire.com/glossary.md#finding) is an issue raised against a trail's branch, typically by a [runner](https://docs.entire.com/cli-reference/runner.md) 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 `<repo>/<number>`. 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 [<trail>] [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-id>
```

### trail finding add

Create a finding on a trail.

```bash theme={null}
entire trail finding add [<trail>] -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 [<trail>] <finding-id> [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 [<trail>] <finding-id> [flags]
```

| Flag | Description |
| - | - |
| `-m, --message TEXT` | Status reason to record. |

### trail finding dismiss

Dismiss a finding.

```bash theme={null}
entire trail finding dismiss [<trail>] <finding-id> [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 [<trail>] <finding-id> [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 [<trail>] <finding-id> [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](https://docs.entire.com/guides/trails/gates.md).

## Continue With

> **[Trails overview](https://docs.entire.com/guides/trails/overview.md)**
>
> Learn how trails group intent, branches, and checkpoints.

> **[Agents](https://docs.entire.com/guides/trails/agents.md)**
>
> Configure the automated evaluations that run on a trail.

> **[Gates](https://docs.entire.com/guides/trails/gates.md)**
>
> Configure the checks a change must pass before it merges.

> **[runner](https://docs.entire.com/cli-reference/runner.md)**
>
> Set up the runners that raise findings on a trail.