trail - Entire

Manage trails: project intent, the repository branches linked to it, discussions, findings, approvals, and merges.

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 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.

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`.

# 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

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.

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.

# 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.

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.

# 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.

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`.

# 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.

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`.

# 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.

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.

entire trail unlink app/7

trail checkout

Check out a trail’s branch.

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.

# 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.

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.

# 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

--force overwrites existing local session logs with the versions stored in checkpoints.

trail watch

Tail events for a trail’s selected repository branch.

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.

# Follow events for the current branch's trail as JSON lines
entire trail watch --json

trail comment

Discuss the whole trail across repositories.

entire trail comment SUBCOMMAND [flags]

Comments are discussions between people on the whole trail. Agents report through findings 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.

entire trail comment list [flags]

trail comment show

Show a discussion and its messages.

entire trail comment show <discussion-id> [flags]

trail comment add

Start a discussion on the trail.

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.

entire trail comment reply <discussion-id> -m BODY [flags]

Flag	Description
`-m, --body TEXT`	Message body. Required.

trail comment edit

Edit a discussion message.

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.

entire trail comment delete <discussion-id> <message-id> [flags]

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

trail comment resolve

Resolve a discussion.

entire trail comment resolve <discussion-id> [flags]

trail comment unresolve

Reopen a resolved discussion.

entire trail comment unresolve <discussion-id> [flags]

# 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.

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.

entire trail approve app/7 -m "Looks good"

trail approvals

List approval decisions on a trail’s selected repository branch.

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.

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 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.

# 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

--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.

entire trail finding [<trail>] [flags]
entire trail finding SUBCOMMAND [flags]

A finding is an issue raised against a trail’s branch, typically by a 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. 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.

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.

entire trail finding show [<trail>] <finding-id>

trail finding add

Create a finding on a trail.

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.

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.

entire trail finding resolve [<trail>] <finding-id> [flags]

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

trail finding dismiss

Dismiss a finding.

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.

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.

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`.

# 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"

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.

Continue With

Trails overview

Learn how trails group intent, branches, and checkpoints.

Agents

Configure the automated evaluations that run on a trail.

Gates

Configure the checks a change must pass before it merges.

runner

Set up the runners that raise findings on a trail.

​Trails and Changes

​Shared Flags

​trail create

​trail list

​trail show

​trail update

​trail link

​trail unlink

​trail checkout

​trail resume

​trail watch

​trail comment

​trail comment list

​trail comment show

​trail comment add

​trail comment reply

​trail comment edit

​trail comment delete

​trail comment resolve

​trail comment unresolve

​trail approve

​trail approvals

​trail merge

​trail finding

​trail finding list

​trail finding show

​trail finding add

​trail finding apply

​trail finding resolve

​trail finding dismiss

​trail finding reopen

​trail finding update

​Continue With

Trails overview

Agents

Gates

runner

Trails and Changes

Shared Flags

trail create

trail list

trail show

trail update

trail link

trail unlink

trail checkout

trail resume

trail watch

trail comment

trail comment list

trail comment show

trail comment add

trail comment reply

trail comment edit

trail comment delete

trail comment resolve

trail comment unresolve

trail approve

trail approvals

trail merge

trail finding

trail finding list

trail finding show

trail finding add

trail finding apply

trail finding resolve

trail finding dismiss

trail finding reopen

trail finding update

Continue With