npm - @allocator-one/harness-cli - Versions diffs - 1.12.1 → 1.14.0 - Mend

@allocator-one/harness-cli 1.12.1 → 1.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +584 -199
package/dist/{chunk-VOH6BBJD.js → chunk-F2YVTB2A.js} +736 -84
package/dist/cli.js +90 -135
package/dist/{server-FNNMISOZ.js → server-75QJASTY.js} +142 -10
package/package.json +2 -1
package/spec/openapi.json +3965 -14

package/README.md CHANGED Viewed

@@ -1,206 +1,548 @@
 # @allocator-one/harness-cli
-CLI and MCP server for [Harness](https://harness.infra.one), allocator.one's
-issue tracker. A standalone Node client — no backend checkout, no Erlang
-toolchain, and no local issue state: issues live server-side, so there is
-nothing to commit or sync.
+The `harness` CLI and MCP server for [Harness](https://harness.infra.one),
+allocator.one's issue tracker. It is a standalone Node client that keeps no
+local issue state. Issues live on the server, so there is nothing to commit or
+sync.
 ## Install
-Zero-install, always current:
 ```sh
-npx -y @allocator-one/harness-cli list --team ALL
+npm i -g @allocator-one/harness-cli
+harness ready
 ```
-Or globally:
+Or run it without installing:
 ```sh
-npm i -g @allocator-one/harness-cli
-harness ready
+npx -y @allocator-one/harness-cli ready
 ```
 Requires Node >= 20.
-## Auth
-No setup needed: commands target `https://harness.infra.one` and start the
-browser login the first time. One login covers every shell, worktree, and
-agent slot on a machine — credentials are stored at
-`~/.config/harness/credentials.json` (0600) as a single `{url, token}` pair,
-and a token is only ever sent to the host that minted it.
-- `harness login` — browser flow (PKCE loopback); `--no-browser` prints the
-  URL and prompts for a pasted token instead.
-- `harness logout` — revokes the stored login server-side and deletes the file.
-- `harness whoami` — shows the resolved host and credential source.
-Headless contexts (agents, CI): mint an `aone_…` API token (admin → API
-tokens) and set `HARNESS_API_TOKEN`. Do not set it in interactive sessions —
-the browser login attributes writes to the real user.
-### Provider keys
-Admins store the org's provider API keys (Anthropic, OpenAI, Google,
-OpenRouter, Brave Search, Perplexity) in Harness under `Settings → Model
-keys`. The CLI hands them to tooling without ever printing them:
-- `harness keys list` — provider slugs the org has keys for and the env var
-  each maps to (`--json` for `{providers: [{provider, env}]}`); values are
-  never shown.
-- `harness keys exec [--only <slugs>] [--override] -- <command> [args…]` —
-  runs the command with the keys in its environment and exits with the
-  command's exit code (128 + signal number when it was signalled). `--only
-  brave,perplexity` passes just those providers and withholds your shell's
-  own copies of the other provider variables, so the tool sees no more than
-  it needs; a requested provider the org has no key for keeps your shell's
-  variable (and says so on stderr). Slugs are trimmed and case-insensitive,
-  and an allowlist that names nothing (`--only ,`) is a usage error, not
-  "everything". Otherwise a variable already set in your shell wins unless
-  `--override` is given; a blank variable counts as unset. `--json` is
-  accepted for uniformity but changes nothing: stdout belongs to the command. A SIGTERM sent to
-  `harness` is forwarded to the command; Ctrl+C reaches the command from the
-  terminal directly and `harness` waits to report its exit. macOS and Linux
-  only.
-Slug → variable, the same table rcl uses: anthropic → `ANTHROPIC_API_KEY`,
-openai → `OPENAI_API_KEY`, google → `GEMINI_API_KEY`, openrouter →
-`OPENROUTER_API_KEY`, brave → `BRAVE_API_KEY`, perplexity →
-`PERPLEXITY_API_KEY`. Reading keys needs the `model-keys:read` scope: login
-tokens carry it, `aone_` tokens must be minted with it. There is deliberately
-no MCP tool for this — a tool result is model-visible text.
-## Environment variables
-| Variable | Effect |
-| --- | --- |
-| `HARNESS_API_URL` | Target host (default `https://harness.infra.one`). https only, plain http allowed against localhost. |
-| `HARNESS_API_TOKEN` | Bearer token (`aone_…`); wins over the stored login. Never inherits the stored login's host. |
-| `HARNESS_TEAM` | Default team key for commands that take `--team`. |
-| `HARNESS_ACTOR` | Write attribution, sent only when explicitly set. |
-| `HARNESS_CACHE_DIR` | Where `show` downloads attached images (default `$XDG_CACHE_HOME/harness/attachments` or `~/.cache/harness/attachments`). Absolute paths only. |
-## For agents
-`harness mcp` runs a stdio MCP server exposing every operation as a typed
-tool — issue_list, issue_show, activity_list, issue_create, issue_update, issue_claim,
-issue_close, issue_comment, issue_comment_edit, issue_comment_delete,
-relation_list/create/update/delete, relation_add/rm (blocking shorthand),
-link_list/add/update/rm,
-project_list/show/create/update, milestone_list/create,
-document_list/show/create/update, label_list/create, team_list,
-team_create, workflow_states, user_list, stats, upload. Read-only tools carry
-`readOnlyHint`. Results are compact JSON of the data envelope.
-Register it with Claude Code:
+## Sign in
+You don't need to configure anything. Commands target
+`https://harness.infra.one`, and the first command you run in a terminal
+opens a browser login and then carries on. One login covers every shell,
+worktree, and agent slot on the machine.
+- `harness login`: browser sign-in (PKCE, loopback callback on 127.0.0.1).
+  `--no-browser` prints the URL and asks you to paste the token instead.
+  `--url <host>` signs in to another host, and `--timeout <ms>` changes how
+  long it waits for the callback (default 3 minutes). Login tokens last
+  about 30 days.
+- `harness logout`: revokes the stored login on the server and deletes it
+  locally.
+- `harness whoami`: shows the resolved host and where the credential came
+  from.
+The automatic login only runs when stdout is a terminal and `CI` is unset
+or empty. Elsewhere (agents, CI, pipes), a command that has no credential
+prints how to authenticate and exits with code `2`. For those headless
+contexts, mint an `aone_…` API token (admin → API tokens) with the
+`harness:read` scope, adding `harness:write` if the workflow changes
+anything (claim, create, update, comment, close), and export it as
+`HARNESS_API_TOKEN`.
+> **Never set `HARNESS_API_TOKEN` or `HARNESS_ACTOR` in an interactive
+> session.** The browser login attributes writes to the real user, and
+> overriding it falsifies the audit trail. Both variables are only for
+> headless CI and agent slots.
+Every identifier includes its team key, as in `CLI-12` or `ALL-4901`. Older
+issues keep legacy prefixes: `IO-` issues were created before team-prefixed
+numbering, `ALL-` numbers up to the import ceiling came from Linear, and
+`BD-` from beads.
+## Daily workflow
 ```sh
-claude mcp add --scope user harness -- npx -y @allocator-one/harness-cli mcp
+harness ready --claim                           # claim the team's next ready, unassigned issue
+harness show CLI-12                             # read it, including attached screenshots
+# … do the work …
+harness close CLI-12 --reason "Implemented in 1a2b3c4"
 ```
-Example tool call: `issue_list` with `{"ready": true, "team": "ALL"}`
-returns the ready queue as JSON; `issue_claim` with `{"id": "IO-123"}`
-claims atomically (a conflict means someone else holds it).
-Read the same mixed timeline shown in an issue's Activity section with
-`harness activity IO-123`. It returns the newest 20 entries and points out
-when older entries exist; pass `--all` to follow the opaque cursors through
-the full history. `activity_list` exposes the same `id`, `limit`, and `all`
-inputs to MCP clients. Assignment, reassignment, and unassignment entries show
-the actor and previous/new assignees when supplied by the server. Unavailable
-identities use safe labels rather than raw user ids.
-Typed issue relations are available without losing the concise blocking
-workflow. `harness dep add|rm` and the `relation_add`/`relation_rm` MCP tools
-remain the blocker-first shorthand; the full surface is:
+**Queue.** `harness ready` lists open, unblocked issues, highest priority
+first. Blocked issues, `hold`-labeled issues, and parents with sub-issues
+that are not completed are excluded. Only a completed blocker resolves: a
+cancelled or archived one still blocks until it is completed or the
+dependency is removed or re-pointed. An issue that is waiting on a wait
+condition (see [Plans](#plans)) is not ready either. `harness blocked` lists
+issues that are waiting on a blocker.
+Both commands take `--team`. `ready` marks agent steps, the plan steps
+Operator runs, with `[agent]` before the title and a legend under the table,
+and `--json` gives every issue an `agent_step` flag. Only the plan driver
+claims an agent step. The issue payload carries no executor, so the CLI
+goes by the team: agent steps are filed in the organization's Operator team
+(named Operator, keyed `OPERATOR`, or `OPERATOR2` and so on). That is a
+heuristic. A step handed back to a person keeps its team and stays marked,
+and the claim itself is the authority.
+**Claim the next issue.** `harness ready --claim` is a single request: the
+server picks the team's most important ready issue that has no assignee
+(urgent, high, medium, low, then none; oldest first, then by id), assigns
+you, and moves it to the team's first started state, all in one transaction.
+Concurrent callers get different issues, and the CLI does no paging, sorting,
+or retrying of its own.
+- It needs a team: `--team`, then `HARNESS_TEAM`, then the repo config. With
+  none of them it is a usage error, and the claim is never sent.
+- `--all`, `--limit`, and `--page` are refused with `--claim`, because the
+  server already ranks the whole ready set.
+- An empty queue is a normal outcome: it prints "Nothing to claim: team CLI
+  has no unassigned ready issues." (`null` with `--json`) and exits `0`.
+- A rate limit, server error, or unreadable response exits `1`, and an
+  unreachable API exits `3`. None of these is reported as an empty queue.
+  The CLI never retries the claim. When an unreadable response or a lost
+  connection leaves it unknown whether the claim landed, the error says to
+  check `harness list --team <key> --assignee me --status in_progress`
+  before claiming again.
+**Read.** `harness show <id>` prints the fields, relations, children, and
+comments. It also downloads the images attached to the issue's description,
+design, acceptance criteria, notes, and comments (up to 20, cached locally)
+and prints their paths. Screenshots are often the reproduction, so read
+them. `--no-images` skips the downloads. If a download fails, a stderr
+notice says so and the command still succeeds. `harness comments <id>`
+prints the full, untruncated comment thread with comment ids. The
+`Blocked:` line names a cancelled or archived blocker as such
+(`yes, by CLI-3 (cancelled), CLI-4 (archived), CLI-5`). When the issue has
+wait conditions, `Waiting:` says how many still hold it, and a
+`Wait conditions:` section lists each one (`[ ] gate "Finance sign-off" · <id>`,
+`[x] not before … (satisfied …)`, `system event`) with the id
+`harness gate satisfy` takes.
+`harness activity <id>` prints the issue's activity timeline: comments,
+creation, and state and assignee changes. It shows the newest 20 entries
+(`--limit` accepts 1–100), and `--all` reads further back.
+**Create.** Creating an issue before you write code keeps the work tracked:
 ```sh
-harness relation list IO-123
-harness relation add IO-123 IO-456 --type related
-harness relation update IO-123 IO-456 --type blocks
-harness relation rm IO-123 IO-456
+harness create --title "Fix login redirect" --type bug --priority high \
+  --description "…" --parent CLI-3 --assignee me --due-date 2026-11-01 \
+  --label regression --idempotency-key fix-login-redirect-1
 ```
-Relation update and removal accept either the relation id from `relation list`
-or a unique related issue identifier. If the same pair has more than one
-relation, the CLI refuses to guess and requires the relation id. Link updates
-use the same safe lookup rule by id or exact URL; the existing `link rm`
-command keeps its first-match behavior for backward compatibility:
+- `--type task|bug|feature|epic` is applied as a `type/<type>` label.
+- `--priority urgent|high|medium|low|none` takes names only. Bare numbers
+  are refused because bd and Harness number priorities differently.
+- `--team <key>` falls back to `HARNESS_TEAM` and then to the repo config.
+  With none of these set, the command is a usage error.
+- `--label` (repeatable) looks for a matching label in the target team first
+  and then at workspace scope. Missing labels are created at workspace scope
+  (which requires Harness administrator standing) before the issue is filed,
+  and the issue is created in a single request with all its labels.
+- `--idempotency-key <key>` (1–200 printable ASCII characters, no leading or
+  trailing space) makes a retry safe. If a create times out, run it again
+  with the same key to get the original issue back instead of a duplicate.
+  The CLI never retries a write on its own.
+- `--design`, `--notes`, and `--acceptance` set the remaining text fields.
+**Update.** `harness update <id>` with:
+- `--claim`: atomic. It assigns you and moves the issue to the team's first
+  started state. A conflict (exit `1`, HTTP 409) names its reason: someone
+  else holds the issue, or it is not claimable yet. Two reasons come with a
+  next step: `agent_step` (Operator runs it; to do it yourself, set its
+  executor to `none` with `harness plan edit <plan-id>` and release the plan
+  again) and `waiting_on_condition` (`harness show` lists what it waits on;
+  tick a gate with `harness gate satisfy`). It cannot be combined with
+  `--assignee`.
+- `--state <name-or-type>`: moves the issue to the workflow state whose name
+  or type matches.
+- `--title`, `--description`, `--design`, `--acceptance`, `--priority`,
+  `--parent`, `--assignee` (`""` unassigns), `--due-date` (`""` clears).
+- `--notes` replaces the notes and `--append-notes` appends to them. Pass
+  only one of the two.
+- `--add-label` / `--remove-label` (repeatable, name or id) add or remove
+  individual labels without replacing the rest. You can only add labels that
+  belong to the issue's team or the workspace, and a missing name is created
+  at workspace scope, as with `create`. If two attached labels match a name,
+  remove by id.
+**Dependencies.** `harness dep add <issue> <blocker>`: **the second argument
+blocks the first.** `harness dep rm <issue> <blocker>` removes the
+dependency. For other relation types, see `relation` under
+[Other commands](#other-commands).
+**Close.** `harness close <id> [<id>…]` closes one or more issues as
+completed. Use `--cancel` to close them as canceled, or `--duplicate-of <id>`
+to close a single issue as a duplicate of the canonical one. The
+duplicate-of form records a duplicate relation and cannot be combined with
+`--cancel`. `--reason` records why the issue is done. The output lists the
+issues each closure unblocked
+(`Closed CLI-12 — unblocked: CLI-13, CLI-14`); act on them instead of
+leaving them in the queue. Only completing releases dependents: a canceled
+issue still blocks them. A duplicate close moves its blocking edges to the
+canonical issue, and any edge that cannot move stays on the duplicate. When
+the closed issue still blocks anything, an indented line names those
+dependents (`Still blocking: CLI-13 (a cancelled issue still blocks its
+dependents)`) so you can remove or re-point those dependencies. With
+several ids, each one is closed on its own.
+A failure prints `FAILED <id>: …`, and the command exits `1` after trying
+the rest. `harness archive <id>…` archives issues, `--restore` brings them
+back, and `harness list --scope archived` lists them.
+**Comment.** `harness comment <id> "text" [--mention <name>]…` posts a
+comment. The server resolves each mention and notifies that person.
+`harness comment edit <id> <comment-id> "new text"` and
+`harness comment delete <id> <comment-id>` (alias `rm`) work on your own
+comments. Comment ids are UUIDs from `harness comments`.
+**Find.** There are two search commands:
+- `harness search <question…>` searches by meaning. It returns a ranked list
+  with an exact identifier first, followed by results ordered by relevance
+  across a lexical and a semantic signal, so it can find issues that share
+  none of your words. Write the question in plain language instead of
+  keywords. Results default to 10 and are capped at 20, with no pages
+  (`--page`/`--all` are accepted but ignored). Archived issues are not
+  searched. If the semantic side is unavailable, stderr says
+  `semantic search unavailable — showing lexical matches only`.
+- `harness list --search <text>` is the paginated lexical filter, which
+  matches title or issue number.
+`harness list` filters: `--status open|in_progress|closed`,
+`--assignee <me|id|email|name|"">` (`""` means unassigned),
+`--created-by <me|id>`, `--involved me`, `--priority <name>`,
+`--label <name>` or `--type <type>` (only one of the two), `--team <key>`,
+`--parent <id>` (children of an epic), and `--scope all|archived`.
+**Overview.** `harness stats` prints per-team and total counts.
+`harness prime` prints those counts, the organization's ten most important
+ready issues across every team (urgent first and priority none last, ranked
+the way `harness ready --claim` ranks, though that claims only unassigned
+issues on one team), and a short workflow reminder. It is meant for the
+start of an agent session. Against a server older than this read it shows
+the ten newest ready issues instead.
+### Text from a file
+When text comes from somewhere other than your own typing, such as issue
+content, a commit message, or model output, pass a file instead of a shell
+argument. Quoting can be defeated: a `"` ends the string, `$(…)`
+substitutes, and a heredoc ends at any flush-left delimiter line the text
+happens to contain.
 ```sh
-harness link update IO-123 https://example.com/old --url https://example.com/new --title "Runbook"
+harness create --title "…" --description-file ./body.md
+harness update CLI-12 --notes-file ./notes.md --acceptance-file ./ac.md
+harness comment CLI-12 --body-file ./comment.md
+git log -1 --format=%B | harness close CLI-12 --reason-file -
 ```
-Issue creation resolves `--label` names within the target team first, then at
-workspace scope. Missing names are created at workspace scope before the issue
-is filed, and the final label ids travel in the single issue-create request, so
-a preparation or permission failure cannot leave an unlabeled issue behind.
-Creating a missing label requires Harness administrator standing.
-Label repair is additive and repeatable; it never implicitly replaces the
-whole set:
+| Command | File options |
+| --- | --- |
+| `create` | `--title-file`, `--description-file`, `--design-file`, `--notes-file`, `--acceptance-file` |
+| `update` | the same five, plus `--append-notes-file` |
+| `close` | `--reason-file` |
+| `comment`, `comment edit` | `--body-file` |
+Other commands (`project`, `milestone`, `doc`, `link`, and so on) take inline
+values only. `plan create` and `plan edit` read a whole JSON or YAML
+document with `--file` (see [Plans](#plans)), under the same stdin and
+UTF-8 rules, up to 8 MB (the API's request limit). `-` reads from stdin, and only one option per invocation can do
+that. stdin must not be a terminal. Passing both the inline and the file form
+of a field is a usage error, and so is a file that produces an empty title,
+reason, or comment. Conflicting options are caught before anything is read,
+so a rejected command never consumes your pipe. A file must be valid UTF-8
+and at most 1 MB, and one trailing newline is dropped, as with
+`$(cat file)`.
+## Plans
+A plan is a root issue and its steps, created in one request: their
+parents, `blocked_by` dependencies, executors, teams and wait conditions.
+Either the whole plan is created or nothing is. Plans start held, so
+nothing runs until a person releases one.
 ```sh
-harness update IO-123 --add-label security --add-label needs-review
-harness update IO-123 --remove-label security
+harness plan create --file plan.yaml --team IO --idempotency-key q3-report
+harness plan show <plan-id>
+harness plan release <plan-id> --collaborator grace@example.com
+harness gate satisfy IO-121 "Finance sign-off"
 ```
-Both update flags accept a label name or id. Additions allow only labels from
-the issue's team or workspace. Removal can target an attached legacy foreign
-label; when attached normalized names are ambiguous, use the label id.
-Auth resolution is identical to the CLI. Without a credential, tools return
-an error telling the agent to run `harness login` in a terminal — the
-server never opens a browser itself.
-### Text from a file, never from a shell argument
-Every free-text option has a `--<field>-file` companion, and `-` means stdin:
+**The plan file** is the API's request body, as JSON (`.json`) or YAML
+(anything else, and stdin with `--file -`). YAML is read as YAML 1.2 and
+held to what JSON can carry: dates stay strings, and a duplicate key, an
+explicit tag such as `!!timestamp`, or `.inf`/`.nan` is refused. The
+root's fields sit at the top level, and each step has a `key` that other
+steps refer to:
+```yaml
+title: Ship the Q3 LP report
+spend_budget_cents: 5000        # needed to release Operator steps
+steps:
+  - key: gather
+    title: Gather the fund data
+    executor: operator          # Operator runs it; the description is its instruction
+    description: Pull the Q3 NAVs for every fund in the portfolio
+  - key: review
+    title: Review the numbers
+    team: IO                    # a person's step; defaults to --team
+    blocked_by: [gather]
+    conditions:
+      - kind: gate
+        label: Finance sign-off
+  - key: send
+    title: Send the report
+    blocked_by: [review]
+    conditions:
+      - kind: not_before
+        not_before: "2026-10-15T09:00:00Z"
+```
-```sh
-harness create --title "…" --description-file ./body.md
-harness update IO-123 --notes-file ./notes.md --acceptance-file ./ac.md
-harness comment IO-123 --body-file ./comment.md
-git log -1 --format=%B | harness close IO-123 --reason-file -
+- A step takes the issue fields (`title`, `description`, `priority` as a
+  number from 0 for none to 4 for low, `assignee`, `label_ids`, …) plus
+  `key`, `parent` (the key of the step that contains it), `blocked_by`
+  (keys), `executor` (`none`, the default, or `operator`), `team`, and
+  `conditions`. Operator steps are filed in the Operator team. Only steps
+  without sub-steps carry an executor, edges, or conditions.
+- Wait conditions: `not_before` (a UTC instant), `gate` (a `label` a person
+  ticks), and `event` (`event`, `subject_id`, and for a stage change
+  `target_id`). The allowed events are `deal_stage_changed`,
+  `opportunity_stage_changed`, `form_submitted`, and `investment_executed`.
+  Every condition must hold before the step is ready.
+- A plan has at most 100 steps, its root included.
+- `--team` (or `HARNESS_TEAM` or the repo config) is the root's team and the
+  default team for people's steps. `--idempotency-key` works as it does for
+  `create`: if a create times out, run it again with the same key to get
+  the same plan back.
+**Validation.** The server checks the whole graph and an invalid plan
+creates nothing. The command exits `1`, and stderr lists every violation by
+the step key it is about:
+```text
+harness: The plan is not valid; nothing was changed (HTTP 422)
+  step "review" (steps[1]): parent names no step of this plan, or no issue in this organization (parent: nope) [unknown_parent]
+  plan: A plan with Operator steps needs a positive spend budget [spend_budget_required]
 ```
-`create` and `update` cover `--title`, `--description`, `--design`, `--notes`
-and `--acceptance` (plus `--append-notes` on `update`); `close` takes
-`--reason-file`, `comment` takes `--body-file`.
+**Show.** `harness plan show <plan-id>` prints the plan's status, budgets,
+revision, and spend estimate, then every step in tree order (indented by
+depth) with its key, executor, state, and status. The status is `ready`,
+`held` (edited since the release), `not in revision` (added after it),
+`waiting` (on a wait condition), `container`, `done`, `cancelled`,
+`archived`, or `-`. The edges and each step's wait conditions come after
+the steps.
+**Edit.** `harness plan edit <plan-id> --file edits.yaml` changes step
+executors and keys, naming each step by its `step` key or `issue`
+identifier, and the budgets (`retry_budget`, `spend_budget_cents`):
+```yaml
+steps:
+  - step: gather
+    executor: none              # hand the step to a person
+```
-Use these whenever the text is not something you authored inline. Prose that
-reaches a shell argument has to survive quoting, and quoting can be defeated —
-a `"` closes the string, `$(…)` substitutes, and a heredoc ends at whatever
-flush-left delimiter line the text happens to contain. Handing over a path
-removes the question, the way `git commit -F` does. This matters most for
-agents relaying issue text they did not write.
+Editing a released step holds it until the plan is released again. A
+budget change needs the plan held first. Descriptions, parents, and edges
+are edited with the issue commands (`update`, `dep`). Conditions are set
+when the plan is created. Editing them later goes through the API's issue
+condition endpoints, which have no command yet; `gate satisfy` ticks a
+gate.
+**Release and hold.** `harness plan release <plan-id>` releases the plan as
+you: it freezes the next revision and lets ready steps run.
+`--collaborator <id-or-email>` (repeatable) adds people to the plan room
+where its Operator steps run, and `--retry-budget` and
+`--spend-budget-cents` set the budgets. `harness plan hold <plan-id>`
+pauses every step until the plan is released again.
+**Gates.** `harness gate satisfy <issue> <gate>` ticks a gate and
+`harness gate unsatisfy <issue> <gate>` unticks it. `<gate>` is the gate's
+label or its condition id from `harness show`. A label matches exactly
+first, then ignoring case, and a label that more than one gate carries is
+refused with their ids. Ticking a gate requires staff standing in the
+organization.
+A server without the plan API answers the plan commands with a 404, and the
+error says that the server may predate plans.
+## Uploads
+`harness upload <path>` uploads a file and prints a markdown reference to
+paste into a description or comment. `--json` returns the URL, filename,
+content type, byte size, and markdown instead.
+- Images (PNG, JPG, WebP, GIF) can be up to 25 MB.
+- Videos must be `.mp4` files of up to 100 MB, with H.264 8-bit 4:2:0 video,
+  optional AAC audio, and optional mov_text subtitles. The server validates
+  the media and does not transcode other formats. Harness shows linked
+  videos as an inline player.
+A new video is private to its uploader until that user saves its link in an
+issue description or comment. After that it follows the access policy of
+the issue that holds it, and reusing the link elsewhere doesn't change who
+owns it. `harness show` downloads images only, never videos. The older
+`attach-image <path>` command accepts images only (25 MB).
+## Other commands
+| Command | Notes |
+| --- | --- |
+| `relation list <issue>` | Every typed relation, with relation ids. |
+| `relation add <issue> <other> --type <t>` | `blocks`, `blocked_by`, `related`, `duplicate`, `duplicate_of`, `duplicated_by`. |
+| `relation update <issue> <relation-id-or-issue> --type <t>` | `blocks`, `blocked_by`, `related`, `duplicate_of`. |
+| `relation rm <issue> <relation-id-or-issue>` | If more than one relation matches the other issue, pass the relation id. |
+| `link list\|add\|update\|rm <issue> …` | URLs attached to an issue. `add <issue> <url> [--title]`; `update <issue> <link-id-or-url> --url … \| --title …` refuses an ambiguous URL; `rm <issue> <link-id-or-url>` removes the first match. |
+| `project list\|show\|create\|update` | `list [--search] [--state]` (paginated). `create --name … [--description] [--summary] [--state] [--lead <user-id>] [--start-date] [--target-date]`. |
+| `milestone list\|create --project <id>` | `create … --name … [--description] [--target-date]`. |
+| `doc list\|show\|create\|update` | `list [--search]` (paginated). `create --title … [--content] [--project <id>]`. |
+| `label list\|create\|update\|delete` | `create <name> [--color]`, `update <id> [--name] [--color]`, `delete <id> --yes` (refused while issues carry the label). |
+| `team list\|create\|rename\|set-default` | `create --key <KEY> --name …` sets up the default workflow states. The key is permanent; `rename <key> --name …` changes only the display name. `set-default <key>` makes the team the org's default filing target. |
+| `state list\|add\|update\|order\|delete` | A team's workflow states (`--team`, else `HARNESS_TEAM` or the repo config). `add --name … --type backlog\|unstarted\|started\|completed\|canceled [--color]`, `order <id,id,…>` (every state id, in order), `delete <id> --yes`. `states` is an alias of `state list`. |
+| `member list\|add\|set-role` | The org's tracker roster. `add --email … --role admin\|staff\|collaborator`, `set-role <user-id> --role …\|none` (`none` revokes). |
+| `user list` | Users, for resolving assignees. |
+| `version` | CLI and server API versions. Works before you log in, and so does `harness --version`. |
+`team rename`, `team set-default`, `label update`, `label delete`, and the
+write commands of `state` and `member` require Harness administrator
+standing, and so does `member list`.
+## Provider keys
-Passing both an inline value and its `-file` for the same field is a usage
-error rather than a silent precedence, and only one field per invocation may
-read stdin. Both are checked before anything is read, so a rejected command
-never consumes your pipe. One trailing newline is dropped, like `$(cat file)`.
+Admins store the org's provider API keys (Anthropic, OpenAI, Google,
+OpenRouter, Brave Search, Perplexity) in Harness under `Settings → Model
+keys`. `harness keys` passes them to tools without ever printing them:
-## Image and video uploads
+- `harness keys list` shows the provider slugs the org has keys for and the
+  environment variable each one maps to (`--json` returns
+  `{providers: [{provider, env}]}`). It never prints the values.
+- `harness keys exec [--only <slugs>] [--override] -- <command> [args…]`
+  runs the command with the keys in its environment and exits with the
+  command's exit code (128 + the signal number if the command was killed by a
+  signal). `--only brave,perplexity` passes just those providers and also
+  removes your shell's own copies of the other provider variables, so the
+  command sees only what it needs. If the org has no key for a provider you
+  requested, your shell's variable is kept and stderr says so. Slugs are
+  trimmed and case-insensitive. An `--only` list that names nothing
+  (`--only ,`) is a usage error, not a request for everything. Without
+  `--override`, a variable that is already set in your shell wins (a blank
+  variable counts as unset). `--json` is accepted but has no effect, because
+  stdout belongs to the command. A SIGTERM sent to `harness` is forwarded to
+  the command. Ctrl+C reaches the command directly from the terminal, and
+  `harness` waits to report its exit. Works on macOS and Linux only.
+Each slug maps to the same variable as in rcl: anthropic → `ANTHROPIC_API_KEY`,
+openai → `OPENAI_API_KEY`, google → `GEMINI_API_KEY`, openrouter →
+`OPENROUTER_API_KEY`, brave → `BRAVE_API_KEY`, perplexity →
+`PERPLEXITY_API_KEY`. Reading keys requires the `model-keys:read` scope.
+Login tokens have it; `aone_` tokens need to be minted with it. There is
+deliberately no MCP tool for keys, because a tool result is text the model
+can read.
+## Scripting contract
+- **`--json` on every command** except `mcp`. It replaces the human output
+  with the response data as JSON. `keys exec` accepts it but changes
+  nothing: its stdout is the child command's output.
+- **stdout carries data only**, so it is safe to pipe. Diagnostics go to
+  stderr:
+  - `→ https://harness.infra.one` on every command that writes, naming the
+    host it sent the write to.
+  - `harness: showing 50 of 132 (page 1 of 3) — pass --all for the rest, or --page to step through.`
+    when a paginated read did not return everything, and
+    `harness: --limit N was capped at M by the server.` when the server
+    reduced the page size you asked for.
+  - The `activity`, `search`, and `show` notices described above.
+  - The update notice (see [Staying current](#staying-current)).
+- **Pagination.** `ready`, `blocked`, `list`, `project list`, and `doc list`
+  return 50 records per page by default (`ready --claim` has no pages). `--limit` changes the page size,
+  `--page` selects a page, and `--all` follows every page (pass `--all` or
+  `--page`, not both). The truncation notice goes to stderr only, so a
+  script that reads just the `--json` output cannot tell a full page from a
+  complete result. Pass `--all` when you need everything.
+- **Exit codes.** `keys exec` returns the command's exit code instead.
+  | Code | Meaning |
+  | --- | --- |
+  | `0` | Success, including `ready --claim` finding nothing to claim. |
+  | `1` | The command failed. Causes include an API error (the message gives the HTTP status, followed by any per-field errors or plan violations, one per line), a response the CLI cannot interpret, a partial failure across several ids, or a local refusal such as an unreadable or oversized upload. |
+  | `2` | Usage or configuration error, including "not signed in" outside a terminal. Nothing was sent. |
+  | `3` | The API was unreachable (DNS, TLS, connection refused, or timeout). Retry with backoff, and if the API stays down, say so instead of dropping tracked work. |
+## MCP server
+`harness mcp` runs an MCP server over stdio. To register it with Claude Code:
-`harness upload ./demo.mp4` prints a reusable markdown reference. Paste it
-into an issue description or comment to show an inline video player. Use
-`--json` for the server's URL, filename, content type, byte size, and markdown.
-The MCP `upload` tool accepts the same local path and returns the same metadata.
+```sh
+claude mcp add --scope user harness -- npx -y @allocator-one/harness-cli mcp
+```
-Images (PNG, JPG, WebP, GIF) can be up to 25 MB. Videos must be `.mp4`, up to
-100 MB, with H.264 8-bit 4:2:0 video, optional AAC audio, and optional mov_text
-subtitles. The server validates the media; it does not transcode other formats.
+With a global install, `harness mcp` works as the command instead of the
+`npx` form. Any other MCP client can use the same command:
-A newly uploaded video is private to its uploader until that user saves its
-link in an issue description or comment. It then follows the owning issue's
-access policy. Reusing the link elsewhere does not change that ownership.
-`harness show` continues downloading images only, never linked videos.
-The older `attach-image` command retains its 25 MB limit.
+```json
+{ "mcpServers": { "harness": { "command": "npx", "args": ["-y", "@allocator-one/harness-cli", "mcp"] } } }
+```
-## Repo config
+The server exposes 58 tools:
-A committed `.harness-cli/config.json`, discovered git-style by walking up
-from the working directory, gives every clone of a repo its defaults:
+| Area | Tools |
+| --- | --- |
+| Issues | `issue_list`, `issue_search`, `issue_show`, `activity_list`, `issue_create`, `issue_update`, `issue_claim`, `issue_close`, `issue_archive` |
+| Comments | `issue_comment`, `issue_comment_edit`, `issue_comment_delete`, `comment_list` |
+| Relations | `relation_add`, `relation_rm` (blocking shorthand: `blocker` blocks `issue`), `relation_list`, `relation_create`, `relation_update`, `relation_delete` |
+| Links | `link_list`, `link_add`, `link_update`, `link_rm` |
+| Projects and docs | `project_list`, `project_show`, `project_create`, `project_update`, `milestone_list`, `milestone_create`, `document_list`, `document_show`, `document_create`, `document_update` |
+| Labels | `label_list`, `label_create`, `label_update`, `label_delete` |
+| Teams and states | `team_list`, `team_create`, `team_rename`, `team_set_default`, `workflow_states`, `state_add`, `state_update`, `state_order`, `state_delete` |
+| People | `member_list`, `member_add`, `member_set_role`, `user_list` |
+| Plans and gates | `plan_create`, `plan_show`, `plan_edit`, `plan_release`, `plan_hold`, `gate_set` |
+| Other | `stats`, `upload` |
+The tools cover the issue workflow and the admin surface. Some commands are
+CLI-only: `keys` (deliberately), `login`/`logout`/`whoami`, `version`, and
+`prime`. Read-only tools carry `readOnlyHint`. Each result is compact JSON
+of the response data. Any stderr notice the CLI would print, such as
+truncation, is added as a second text item. A partial failure across several
+ids is returned as an error, with the details for each id in the JSON.
+Some tools behave differently from their commands:
+- `issue_list` with `ready: true` or `blocked: true` accepts every list
+  filter. The CLI's `ready` and `blocked` take only `--team`.
+- `issue_list` only lists. Claiming the team's next issue (`ready --claim`)
+  is CLI-only; over MCP, claim a specific issue with `issue_claim`.
+- `issue_show` downloads images only when you pass `images: true`.
+- `state_delete` and `label_delete` don't need the CLI's `--yes`.
+- `plan_create` takes the plan as an object (`plan`), with `team` and
+  `idempotency_key` beside it, instead of a file. Its schema describes the
+  steps and conditions, and keys inside `plan` that the schema does not
+  know are still sent, so the server reports them. `plan_edit` takes
+  `steps`, `retry_budget`, and `spend_budget_cents` directly. As with every
+  tool, a top-level argument the tool does not declare is dropped.
+  `gate_set` takes `issue`, `gate`, and `satisfied`.
+- An API error's details come back in the tool error text: a validation
+  error's fields, and an invalid plan's violations, one per line by step
+  key.
+- `issue_list` with `ready: true` gives every issue an `agent_step` flag,
+  read from its team as `ready` does.
+For example, `issue_list` with `{"ready": true, "team": "CLI"}` returns the
+ready queue, and `issue_claim` with `{"id": "CLI-12"}` claims an issue
+atomically. `issue_close` takes `ids`, `reason`, `cancel`, and
+`duplicate_of`, and `issue_create` takes an `idempotency_key` for safe
+retries.
+The MCP server resolves auth exactly as the CLI does, on every call, so a
+login completed while the server is running takes effect without a restart.
+It never opens a browser. Without a credential, a tool returns an error that
+tells the agent to run `harness login` in a terminal or set
+`HARNESS_API_TOKEN`.
+## Configuration
+### Repo config
+A committed `.harness-cli/config.json`, found by walking up from the working
+directory the way git finds `.git`, gives every clone of a repo the same
+defaults:
 ```json
 { "team": "CLI" }
@@ -208,47 +550,90 @@ from the working directory, gives every clone of a repo its defaults:
 | Field | Effect |
 | --- | --- |
-| `team` | Default team key. Precedence: `--team` > `HARNESS_TEAM` > repo config. |
-| `url` | Target host. `HARNESS_API_URL` wins. Tokens stay host-bound: a stored login only serves the host that minted it, an env `HARNESS_API_TOKEN` refuses to pair with a repo-named host (set `HARNESS_API_URL` explicitly), and before the interactive auto-login opens a browser at a host named only by the repo, the CLI asks once per host (remembered in `~/.config/harness/trusted-hosts.json`). |
-| `org` | Reserved for Harness org-scoping; parsed today, `url` wins meanwhile. |
-This is config, not state — issues stay server-side.
-## Development
+| `team` | Default team key. Precedence: `--team`, then `HARNESS_TEAM`, then the repo config. |
+| `url` | Target host. `HARNESS_API_URL` takes precedence. Before an automatic login opens a browser at a host that only the repo names, the CLI asks for confirmation, once per host. |
+| `org` | Reserved. It is parsed but has no effect yet. |
-```sh
-npm ci
-npm run typecheck
-npm test
-npm run build          # bundles to dist/cli.js (tsup)
-node dist/cli.js version
-```
+A malformed file is ignored with a warning on stderr.
-The OpenAPI spec is vendored at `spec/openapi.json` and TypeScript types are
-generated into `src/generated/` (committed, so npx consumers never run
-codegen):
+### Hosts and tokens
-```sh
-npm run spec:refresh   # fetch the spec from a live host (uses your login)
-npm run codegen        # regenerate src/generated/api.ts from the vendored spec
-```
+The host comes from `HARNESS_API_URL`, then the repo config's `url`, then
+the host of the stored login, then `https://harness.infra.one`. Tokens are
+bound to the host that issued them. A stored login is only sent to the host
+that issued it. `HARNESS_API_TOKEN` is only sent to `HARNESS_API_URL`, or to
+the default host when that variable is unset. It is never sent to the stored
+login's host, and when a repo config names another host, the command
+refuses with exit code 2 instead of sending the token there. Set
+`HARNESS_API_URL` explicitly if you do mean that host. Without
+`HARNESS_API_TOKEN`, a repo-named host needs a login of its own, and the
+automatic login asks for confirmation first, as described above. Plain
+`http://` is accepted only for localhost.
-CI regenerates the types and fails on drift.
+### Environment variables
-## Release
+| Variable | Effect |
+| --- | --- |
+| `HARNESS_API_URL` | Target host (https, or http against localhost only). |
+| `HARNESS_API_TOKEN` | An `aone_…` API token. It takes precedence over the stored login. Headless use only. |
+| `HARNESS_ACTOR` | Write attribution, sent only when set. Without it the server attributes writes to the signed-in user, or for `aone_` tokens to the token's name. Headless use only. |
+| `HARNESS_TEAM` | Default team key for commands that take `--team`. |
+| `HARNESS_CACHE_DIR` | Where `show` stores downloaded images. Must be an absolute path. |
+| `HARNESS_NO_UPDATE_CHECK` | Set to a value other than `0`, `false`, or `no` to turn off the update notice and the automatic upgrade. |
+| `HARNESS_AUTO_UPGRADE=0` | Keeps the notice but never installs anything (`false` and `no` also work). |
+| `CI` | Any value other than empty, `0`, `false`, or `no` turns off the update notice and automatic upgrade. Separately, any non-empty value, including `0`, stops the automatic browser login. |
+| `XDG_CONFIG_HOME`, `XDG_CACHE_HOME` | Used instead of `~/.config` and `~/.cache` when set to absolute paths. |
-First bump `package.json` and `package-lock.json` through a pull request. After
-that PR is squash-merged, fetch `main` and tag the merge commit — never the
-pre-merge branch tip. Pushing the tag starts the Release workflow, which builds,
-tests, and publishes to npm:
+### Files
-```sh
-git fetch origin main
-git tag -a vX.Y.Z MERGE_COMMIT_SHA -m "Release vX.Y.Z"
-git push origin vX.Y.Z
-```
-Publishing requires the `NPM_TOKEN` actions secret (an automation token for
-the `allocator-one` npm org). Provenance attestation is disabled: npm only
-accepts it from public source repositories, and this repo is private — turn
-`--provenance` back on in `release.yml` if the repo ever goes public.
+| Path | Contents |
+| --- | --- |
+| `~/.config/harness/credentials.json` | The stored login: one `{url, token}` pair, mode 0600. |
+| `~/.config/harness/trusted-hosts.json` | Repo-config hosts you agreed to log in to. |
+| `~/.cache/harness/attachments/` | Images downloaded by `show` (or `HARNESS_CACHE_DIR`). |
+| `~/.cache/harness/update-check.json` | The daily update-check stamp. |
+| `~/.cache/harness/upgrade.lock` | Held while an automatic upgrade runs. |
+None of these files is tracker state: issues stay on the server. The
+attachment cache does hold copies of issue images, so clear it when you no
+longer need them.
+## Staying current
+**Notice.** Each run reads the cached stamp and prints at most one stderr
+line when a newer release exists:
+`harness: 1.13.0 is available (you have 1.12.1) — npm i -g @allocator-one/harness-cli@latest`.
+When the stamp is more than a day old, a detached background process
+refreshes it from the npm registry. A command never waits on that network
+request. The notice applies only to global and project-local installs, not
+to `npx` or a git checkout.
+**Automatic upgrade on HTTP 426.** The CLI sends its version with every
+request, and the server refuses versions below its minimum with a 426. In
+that case the CLI runs
+`npm install --global --ignore-scripts @allocator-one/harness-cli@latest`,
+re-runs the original command, and exits with that command's exit code.
+Re-running is safe only for this status. The server answers 426 before
+authentication and before the request handler, so the refused request
+changed nothing. The CLI never retries any other failure. The upgrade is
+limited by these guards:
+- It only upgrades a global install, located through `npm root -g`, and
+  only when that directory is writable.
+- Only one upgrade runs at a time on a machine (a lock under
+  `~/.cache/harness`). A process that finds a newer version already
+  installed re-runs with it directly.
+- `--ignore-scripts` means an unattended upgrade never runs package scripts.
+- The re-run carries `HARNESS_UPGRADED=1`, so each command is upgraded at
+  most once.
+- It is skipped for `npx`, project-local installs, git checkouts, inside
+  `harness mcp`, under `CI`, and when `HARNESS_NO_UPDATE_CHECK` or
+  `HARNESS_AUTO_UPGRADE=0` is set.
+When the upgrade is skipped or fails, the command prints the server's
+message, adds the reason if the upgrade was attempted, and exits `1`.
+---
+Building, testing, and releasing this package are covered in `AGENTS.md`
+in the (private) source repository.