**Date:** 2026-08-21

**Commits measured:** `81e4c25eb5b5` (`openagents/main`, the forge) for the API; `5bd0061e4f6e` in the `openagents` monorepo for `packages/openagents-cli` (package version `0.1.7`)

**Status:** Stages 1, 2, and 7 shipped. Stage 1 added `openagents api` in `@openagentsinc/cli@0.2.1`. Stages 2 and 7 added optional-bearer issue reads and repository-scoped Projects V2 routes on 2026-08-22. Historical measurements below retain the original findings.

**Status:** Stage 1 and Stage 7 shipped. The issue portion of Stage 2 shipped;

ancillary comment, label, assignee, and milestone reads remain public-only.

Stage 1 added `openagents api` in `@openagentsinc/cli@0.2.1`. Stage 7 added

repository-scoped Projects V2 routes on 2026-08-22. Historical measurements

below retain the original findings.

**Question:** Does the CLI only cover repository upload? What of the Issues and Projects API does it reach? Should that coverage be generated from an OpenAPI document instead of hand-written? What is the fastest honest path to managing issues and projects from a terminal?

**Method:** direct reading of `lib/openagents_web/router.ex`, every controller it routes to under `/api/v3`, the contexts behind them (`lib/openagents/issues.ex`, `labels.ex`, `milestones.ex`, `projects.ex`, `repositories.ex`), the auth plugs, `lib/openagents_web/route_authority.ex`, `priv/api-contracts/repositories-v1.json` and its controller and test, and `docs/openagents-cli/`; plus direct reading of all 21 source files in the `openagents` monorepo at `packages/openagents-cli/src/` and its tests. The CLI lives in a different repository, so every CLI citation names it. Claims that neither repository can settle are in section 7 with the command that would settle them.

> write policy to every project operation, and supports authenticated reads of

> private issues. The `initial_repository!/0` and `initial_path/0` shortcuts no

> longer exist. The findings below describe the pre-remediation surface.

> The CLI guides now document `openagents api`, Issues and Projects recipes,

> and the absence of named `issue` and `project` commands. The stale claim that

> `repo delete` and generic API access were unavailable is fixed.

The owner is right. The CLI is repository-shaped and reaches **none** of the Issues and Projects API.

At the measured commits, the owner was right: the CLI was repository-shaped

and reached **none** of the Issues and Projects API.

The numbers are clean. The router exposes **50 routes under `/api/v3`** (`lib/openagents_web/router.ex:229`, `:253`, `:259`). The CLI calls **11 of them** — the authenticated user, repository create, list, view, delete, the two import routes, import status, and the two device-authorization routes. Those 11 are exactly the routes named in the hand-written contract document at `priv/api-contracts/repositories-v1.json:18`. The other **39 routes — every issue, comment, label, milestone, assignee, and project endpoint — have no CLI surface at all**, and the CLI's own documentation says so: `docs/openagents-cli/command-reference.md:3` scopes the tool to "authentication and hosted repositories", and `:171` lists a generic API command among the things the release does not provide.

At those commits, the router exposed **50 routes under `/api/v3`**

(`lib/openagents_web/router.ex:229`, `:253`, `:259`). The CLI called **11 of

them**: the authenticated user, repository create, list, view, delete, the two

import routes, import status, and the two device-authorization routes. The

other **39 routes** had no CLI surface. The current `openagents api` command

now reaches them without adding named commands.

There is **no OpenAPI document**. What exists instead is a 99-line hand-written JSON artifact served at `/api/contracts/repositories-v1.json` (`lib/openagents_web/router.ex:222`). It lists endpoints as opaque `"METHOD /path"` strings, has no types, no request bodies, no response schemas, and no status codes. It covers 11 of the 50 routes. Nothing derives it from the router, and nothing verifies it against the router.

Confirmed, with one refinement. "Repo upload stuff" understates it slightly — the CLI also does device-flow authentication, credential storage, Git credential-helper installation, repository listing, viewing, cloning, and deletion, and it waits on durable provisioning and import state machines. But on the substance the belief is exactly right: **the CLI has no issue, comment, label, milestone, assignee, or project command, and calls no endpoint in those families.** Its own reference documentation states the boundary (`docs/openagents-cli/command-reference.md:3`, `:171`) and its `README.md` in the monorepo has sections only for install, API selection, sign-in, and repositories.

One documentation defect found in passing, relevant because it is evidence for section 4: `docs/openagents-cli/command-reference.md:173` says the release "does not provide `repo delete`" while the same file documents `repo delete` in full at `:122`, the command exists at `cli.ts:756`, and `docs/openagents-cli/index.md:34` describes it as available. A hand-maintained description drifted from the thing it describes, in the smallest possible surface, in the same file.

One documentation defect found at the measured commit remains relevant as

evidence for section 4: the command reference said the release did not provide

`repo delete` while the same file documented the command. The 2026-08-22

documentation reconciliation fixed that contradiction and added the missing

generic API reference.

---

### Stage 1 — Ship `openagents api` (CLI repository only, small) — SHIPPED 2026-08-21

Add one leaf command taking a path, an optional `-X/--method`, repeated `-f key=value` body fields or `--input -` for raw JSON, and honoring the existing `--json` and profile flags. **Seam:** `packages/openagents-cli/src/cli.ts` plus a thin passthrough client in the `openagents` monorepo; no schema, no server change. **Size:** 150–250 lines with tests. **Effect:** every one of the 50 endpoints becomes reachable from a terminal, and every future endpoint arrives free. Also update `docs/openagents-cli/command-reference.md:171`, which currently lists a generic API command among the things the release does not provide, and fix the stale `repo delete` claim on the same line while you are in there.

Add one leaf command taking a path, an optional `-X/--method`, repeated `-f key=value` body fields or `--input -` for raw JSON, and honoring the existing `--json` and profile flags. **Seam:** `packages/openagents-cli/src/cli.ts` plus a thin passthrough client in the `openagents` monorepo; no schema, no server change. **Size:** 150–250 lines with tests. **Effect:** every one of the 50 endpoints becomes reachable from a terminal, and every future endpoint arrives free. The CLI documentation reconciliation on 2026-08-22 removed the stale claims that generic API access and `repo delete` were unavailable and added tested Issues and Projects recipes.

**What shipped.** `eaa2aa1006` in the `openagents` monorepo, released as

`@openagentsinc/cli@0.2.1`. The command is `openagents api <path>`: a path

yours. A passthrough is faithful by design: it exposes those surfaces exactly

as they are, including where they are wrong.

### Stage 2 — Let an authenticated caller read their own private issues (this repository only, medium)

### Stage 2 — Let an authenticated caller read their own private issues (this repository only, medium) — PARTIALLY SHIPPED 2026-08-22

Issue list and detail reads now accept an optional bearer and authorize private

repository members. The comment, label, milestone, and assignee read routes

remain in the public-read pipeline, so the broader stage is not complete.

Move the issue, comment, label, milestone, and assignee read routes (`router.ex:235`–`:246`) from `pipe_through :api` into `pipe_through :optional_forge_api`, and change the resolution calls in `IssueController`, `CommentController`, `IssueLabelController`, `IssueAssigneeController`, `LabelController`, `MilestoneController`, and `AssigneeController` from `Repositories.get_public_by_path!/2` to `Repositories.get_visible_by_path!/3`, threading `conn.assigns.current_user` (which the optional plug sets to `nil` for anonymous callers). The visibility filters inside `Issues.get_issue_by_path!/3` (`issues.ex:159`), `Issues.get_comment_by_path!/3`, `Labels.get_label_by_path!/3`, and `Milestones.get_milestone_by_path!/3` need the same treatment. **Seam:** router pipelines, ten or so controller call sites, four context queries, and the `RouteAuthority` policy at `route_authority.ex:184`, whose `:public_read` classification for these paths becomes wrong. **Size:** medium; mechanical but wide, and every one of these controllers already has a test file to extend. **Effect:** additive and backward-compatible — anonymous callers see exactly what they see today; the change is that a bearer token now widens the result instead of being discarded. Without this, sections 3.1 ranks 1, 2, 8, and 9 only ever work on public repositories, so this gates most of the value of Stage 3.

### What makes issue management usable this week versus complete

Stages 1 and 2 make it usable — the passthrough covers everything, and the read fix makes private repositories work. Stage 3 makes it pleasant. Stages 4 through 7 make it complete. Stage 5 is what makes it stay correct, and it is deliberately not early: deriving a document from a surface that Stages 2, 4, and 7 are still reshaping means regenerating it three times.

Stage 1 makes every implemented route reachable. The shipped portion of Stage

2 makes private issue list and detail reads usable. Completing Stage 2 makes

the ancillary issue workflow usable for private repositories, and Stage 3

makes the common workflow concise. Stages 4 through 7 complete more of the

contract. Stage 5 keeps the server and client descriptions aligned.

### The cross-repository cost, and how to handle it

The CLI ships from the `openagents` monorepo as `@openagentsinc/cli`, published to npm at version `0.1.7`, with its own `verify` pipeline (format, lint, typecheck, test, build) and its own release cadence. This repository deploys on its own. Four rules keep that from becoming a coordination tax:

The CLI ships from the `openagents` monorepo as `@openagentsinc/cli`, currently

published to npm at version `0.2.1`, with its own `verify` pipeline (format,

lint, typecheck, test, and build) and its own release cadence. This repository

deploys on its own. Four rules keep that from becoming a coordination tax:

1. **Order every stage server-first.** A released CLI in a user's `$PATH` will meet a deployed server. The reverse — a server change that only works with an unreleased CLI — creates a window where the published tool is broken. Stages 2, 4, and 7 land and deploy before the CLI stage that depends on them.

2. **Never require simultaneous merges.** Each stage above touches exactly one repository, by construction. Stage 2 is additive: anonymous reads keep their current behavior, so no released CLI breaks.

## 7. Open questions

- **Does the published npm package's vendored contract match the deployed server's?** Both working copies hash to `5be86539258c…`, but a stale local build in the CLI's gitignored `dist/` carries `9355cac5191e…`, which suggests the constant has changed at least once. Settle with `npm pack @openagentsinc/cli@0.1.7`, then `shasum -a 256 package/contracts/repositories-v1.json`, and compare against `curl -s https://openagents.com/api/contracts/repositories-v1.json | shasum -a 256`.

- **Is the absence of any visibility predicate on the four project reads intentional?** `ProjectController.index`, `show`, `items`, and `fields` apply none (`project_controller.ex:8`, `:41`, `:53`, `:144`), unlike every sibling controller. The pinning to one repository may be masking it. A test asserting that a project on a private repository is not listed anonymously would settle the policy either way.

- **Does the published npm package's vendored contract match the deployed server's?** Both measured working copies hash to `5be86539258c…`, but the CLI still verifies only its vendored copy. Compare the packed `@openagentsinc/cli@0.2.1` artifact with the deployed `/api/contracts/repositories-v1.json`, then make the comparison a staging verification failure.

- **Which ancillary reads should accept an optional bearer?** Repository,

  issue, and project base reads now authorize private repository members.

  Comment, label, assignee, and milestone reads remain public-only.

- **Is `forge:read` in `route_authority.ex:184` an aspiration or a mistake?** If the intent is a read-only token scope, it needs adding to `@allowed_scopes` (`lib/openagents/api_tokens.ex:12`) and a `:forge_read_api` pipeline; if not, the label should say `forge:write`. Settle by asking whether a token that can file an issue should also be able to delete a repository, which is today's answer.

- **Does anything consume the `{"issues": [...]}` envelope, or could the list endpoints move to bare arrays for GitHub compatibility?** Settle by grepping the `openagents` monorepo and this repository's web layer for consumers before Stage 5 freezes the shape into a generated document.

- **What is the intended pagination convention across the whole API?** Repositories use opaque cursors and issues are offset-paged internally. Stage 4 has to pick one, and the choice belongs to whoever owns the contract document, not to the first endpoint that needs a page.

Reporters who later become contributors get roles through the members page;

that is a deliberate human decision, not an automatic upgrade.

### API recipes

### CLI and API recipes

Use `openagents api` for the normal terminal workflow. It selects the API

origin, reads the stored `oa_pat_` credential, and keeps successful JSON on

standard output.

Read open issues:

```sh

openagents api \

  'repos/OpenAgentsInc/openagents.com/issues?state=open'

```

Create an issue with an existing label:

```sh

printf '%s' \

  '{"title":"Search returns duplicates","body":"Steps to reproduce...","labels":["bug"]}' | \

  openagents api -X POST --input - \

  repos/OpenAgentsInc/openagents.com/issues

```

Close an issue as not planned:

```sh

printf '%s' '{"state":"closed","state_reason":"not_planned"}' | \

  openagents api -X PATCH --input - \

  repos/OpenAgentsInc/openagents.com/issues/42

```

The published CLI does not yet provide named `issue` or `project` commands.

See [Call the API with the OpenAgents CLI](openagents-cli/api.md) for project,

item, and scripting examples.

Use `curl` when you need to verify the HTTP boundary without the CLI.

Read (anonymous, public repository):

Date: 2026-08-21

Status: Proposed plan for organizing the OpenAgents backlog and completing the

Issues and Projects product

Status: Active program. The three projects and initial tracking issues exist in

production. Private issue reads and repository-scoped Projects V2 routes have

shipped; the remaining tracks stay open.

## Decision summary

tracking issue and keep every checklist entry linked to a real issue.

Finish the server contract before building rich clients on top of it. The

current API lets a token create an issue in a private repository and then

cannot read it back, leaves issue lists unbounded, and pins Projects V2 to the

initial repository. Those defects can make a polished CLI confidently do the

wrong thing.

private issue-read asymmetry and initial-repository Projects V2 pin are fixed.

Issue lists remain unbounded, ancillary issue-resource reads remain

public-repository only, and the Projects model still lacks lifecycle and

cross-repository operations.

The generic `openagents api` command landed in the `openagents` monorepo at

`eaa2aa1006`, so every current route is already reachable from a terminal.

Named issue and project commands are now in flight in another agent's work.

Treat that CLI lane as active work: do not start a second implementation, and

do not make the server plan depend on an unmerged CLI branch.

`eaa2aa1006` and ships in `@openagentsinc/cli@0.2.1`, so every current route is

reachable from a terminal. The published CLI does not include named `issue` or

`project` commands. Coordinate with any active CLI task before you start D1

through D5, and do not make the server plan depend on an unmerged CLI branch.

## Scope and evidence

The repository's code, tests, authority ledger, and current operator decisions

remain the executable constraints.

## Current work records

Production now uses the structure recommended by this assessment:

- Project 1, **openagents.com roadmap**, holds the public product outcomes.

- Project 2, **Issues and Projects delivery**, holds the server and CLI

  delivery work.

- Project 3, **Agent work and provenance**, holds issue-to-agent and

  issue-to-release work.

- Issue 9, **Deliver the Issues and Projects work system**, tracks the delivery

  program.

- Issue 10, **Connect issues to agent work and release receipts**, tracks the

  provenance program.

- Issues 4 and 8 closed after private issue reads and repository-scoped

  Projects V2 routes deployed.

- Issues 5, 6, and 7 remain open for pagination and filters, request-origin

  URLs, and route-authority reconciliation.

- `OpenAgentsInc/openagents` issue 1 tracks the published CLI's stale embedded

  version value without duplicating the named-command work.

The project item statuses reflect deployed work, not branch state. Update them

only after the target environment has a release receipt.

## What exists now

### Issues

Important missing issue capabilities include:

- Authenticated API reads for private repositories.

- Optional-bearer private reads for comments, labels, assignees, and

  milestones. Issue list and issue detail private reads have shipped.

- A documented, bounded API pagination contract and the web filters on the

  API list route.

- Cross-repository and organization issue API views.

The project layer remains an early implementation, not a complete work

system:

- Projects V2 API reads and creation resolve through the initial-repository

  constants instead of the repository or namespace requested by the caller.

- Project API reads do not apply the same visibility rule as their sibling

  issue routes.

- The API has inconsistent creation and read paths.

- Repository-scoped Projects V2 routes now resolve the repository in the path,

  apply public or member visibility, and use one consistent route family.

- The board cannot remove, reorder, or move an item directly. It does not

  render an item activity trail or show why an item changed status.

- The web board ignores the project's stored field definitions and always

The generic command is not the end-user issue experience. Named commands need

repository inference, concise tables, issue-number arguments, editor support,

confirmation for destructive actions, and stable machine output. That work is

in flight elsewhere. The server should provide correct, testable routes while

the CLI agent owns the named command experience.

confirmation for destructive actions, and stable machine output. They are not

part of the published CLI. The server must keep providing correct, testable

routes while a coordinated CLI task owns the named command experience.

### Agent and receipt infrastructure

| A6 | `openagents.com` | Publish a complete derived API route inventory | CI derives the route list from the router and fails when the published contract omits a route. Response schemas may remain incremental and explicit. |

| A7 | `openagents` | Compare the CLI contract with the configured server | CLI verification fetches the published contract from staging and fails on divergence instead of hashing only its vendored copy. |

A1 through A5 precede a stable named CLI release. A6 and A7 can follow after

the routes stop moving, but the route-coverage failure should land early.

A1 is partially complete: optional-bearer issue reads shipped, while ancillary

comment, label, assignee, and milestone reads remain. A2 through A5 still

precede a stable named CLI release. A6 and A7 can follow after the routes stop

moving, but the route-coverage failure should land early.

### Track B: Complete the issue work record

| C9 | `openagents.com` | Add public project reading | Anonymous users can read a project only when every exposed item and field is safe under the project's visibility policy. |

| C10 | `openagents.com` | Add project activity and live updates | Item and field changes update connected clients and record who changed what. |

C1 and C2 require a written migration and URL compatibility decision. Do not

silently reinterpret existing repository-local project numbers.

C1 shipped through repository-scoped routes without reinterpreting existing

repository-local project numbers. C2 still requires a written ownership and

cross-repository membership decision.

### Track D: Finish the named CLI experience

This track belongs to the agent already working in the `openagents` monorepo.

Use this list to coordinate scope, not to start duplicate work.

The published `openagents` monorepo does not contain these named commands. Use

this list to coordinate with any active CLI task and avoid duplicate work.

| ID | Repository | Issue | Completion signal |

| --- | --- | --- | --- |

### Phase 1: Make the current contract safe to build on

Complete A1 through A5 and C1. This phase fixes authorization, pagination,

origins, errors, route authority, and project addressing. Deploy it before the

named CLI reads or project commands claim support.

Complete the remaining A1 work and A2 through A5. C1 has shipped. This phase

finishes authorization, pagination, origins, errors, and route authority.

Deploy it before named CLI reads claim complete private-resource support.

### Phase 2: Complete core project operations

Answer these questions in decision records before migrations or public API

changes make the answers expensive to revise.

## Immediate next actions

## Next actions

1. Create the **Issues and Projects delivery** tracking issue from this

   document and add A1, A2, A3, A5, and C1 as its first child issues.

2. Identify the active named-CLI task and link D1 through D5 to it without

   duplicating its implementation.

3. Create a decision record for project ownership and cross-repository items.

4. Add owners, milestones, acceptance criteria, and linked implementation

1. Finish issue 5 for bounded issue API pagination and filters.

2. Finish issue 6 for request-origin URLs and issue 7 for route-authority

   reconciliation.

3. Create a decision record for project ownership and cross-repository items

   before C2 changes the repository-local model.

4. Coordinate D1 through D5 with the active CLI owner, if one exists. Keep

   `openagents api` documented and supported until named commands qualify.

5. Add owners, milestones, acceptance criteria, and linked implementation

   issues to the current roadmap cards. Move them to the six-status workflow

   after C6 lands.

5. Fix server authorization and project addressing before qualifying named

   commands.

6. Add the issue-to-work-job relationship as a read-only link after the core

   server correction lands.

7. Use the resulting system to track every later change in this plan.

6. Add the issue-to-work-job relationship as a read-only link under issue 10.

7. Use these Issues and Projects records to track every later change in this

   plan.

surface. Project update/delete, item delete/read, field mutation, views,

ordering, draft items, and organization projects remain unimplemented.

## CLI access

`@openagentsinc/cli@0.2.1` exposes the complete implemented surface through

`openagents api`. The published CLI does not yet provide named `issue` or

`project` commands.

```sh

openagents api 'repos/OWNER/REPOSITORY/issues?state=all'

openagents api repos/OWNER/REPOSITORY/projectsV2

```

See [Call the API with the OpenAgents CLI](openagents-cli/api.md) for request

bodies, response envelopes, Issues recipes, and Projects recipes.

## Enforced authority contract

These are current measured behaviors:

- Issue creation with a nonexistent label returns 422; only the

  add-labels-to-issue endpoint creates labels on the fly, matching GitHub.

- Optional-bearer private reads cover repository, issue, and project base

  routes. Comment, label, assignee, and milestone read routes remain

  public-repository reads.

- Nonnumeric issue and milestone numbers can produce `500 Internal Server

  Error` instead of `404 Not Found`.

- Error envelopes and pagination/link headers are a bounded local contract,

  not complete Octokit or `gh` parity.

# Call the API with the OpenAgents CLI

The `openagents api` command sends an authenticated request to any OpenAgents

API route and writes the response body as JSON. Use it for Issues, Projects,

and other routes that do not have a named CLI command.

The current release does not provide `openagents issue` or

`openagents project` commands. `openagents api` is the supported terminal path

for those resources.

## Before you begin

Install the CLI and sign in to the API profile you intend to use:

```sh

npm install --global @openagentsinc/cli@latest

openagents auth login

openagents auth status

```

You can also set `OPENAGENTS_TOKEN` to an `oa_pat_` user token for one process.

The token must carry the authority required by the route. Public API reads may

allow anonymous HTTP requests, but `openagents api` still resolves an

authenticated CLI session before it sends a request.

## Address a route

A relative path resolves under `/api/v3/`:

```sh

openagents api repos/OWNER/REPOSITORY/issues

```

These paths name the same route:

```text

repos/OWNER/REPOSITORY/issues

/api/v3/repos/OWNER/REPOSITORY/issues

```

An absolute path must start with `/api/`. A complete URL must use the exact API

origin selected by `--profile`, `--api-url`, or the CLI configuration. The CLI

refuses another origin and refuses paths that escape the API namespace.

## Select a method and body

Use `-X` or `--method` to select `GET`, `POST`, `PATCH`, `PUT`, or `DELETE`.

Without the flag, a request without a body uses `GET`, and a request with a

body uses `POST`.

Use repeatable `-f` or `--field` flags for a flat JSON object whose values are

strings:

```sh

openagents api -X POST \

  -f title="Search returns duplicates" \

  -f body="Include steps to reproduce" \

  repos/OWNER/REPOSITORY/issues

```

Use `--input` for numbers, booleans, arrays, nested objects, or `null`:

```sh

openagents api --input request.json repos/OWNER/REPOSITORY/issues

printf '%s' '{"labels":["bug"],"milestone":3}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/issues/41

```

`--input -` reads standard input. `--field` and `--input` are mutually

exclusive.

Use repeatable `-H` or `--header` flags for route-specific headers:

```sh

openagents api -H 'Idempotency-Key: WORK_ITEM_ID' ROUTE

```

The CLI supplies the bearer credential from the selected session and refuses

an `Authorization` header override.

## Work with issues

List open issues. The API returns an object with an `issues` array:

```sh

openagents api repos/OWNER/REPOSITORY/issues

openagents api 'repos/OWNER/REPOSITORY/issues?state=all' | \

  jq -r '.issues[] | [.number, .state, .title] | @tsv'

```

Read one issue and its comments:

```sh

openagents api repos/OWNER/REPOSITORY/issues/41

openagents api repos/OWNER/REPOSITORY/issues/41/comments

```

Create, edit, close, and reopen an issue:

```sh

openagents api -X POST \

  -f title="Search returns duplicates" \

  -f body="Steps to reproduce" \

  repos/OWNER/REPOSITORY/issues

openagents api -X PATCH -f title="Search duplicates results" \

  repos/OWNER/REPOSITORY/issues/41

printf '%s' '{"state":"closed","state_reason":"completed"}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/issues/41

openagents api -X PATCH -f state=open \

  repos/OWNER/REPOSITORY/issues/41

```

Add a comment:

```sh

openagents api -X POST -f body="The fix is available in staging." \

  repos/OWNER/REPOSITORY/issues/41/comments

```

The [GitHub-shaped Issues and Projects API

assessment](../github-api-issues-projects-assessment.md) lists the implemented

label, assignee, milestone, comment, and issue-label routes.

## Work with projects

List repository projects. The API returns an object with a `projects` array:

```sh

openagents api repos/OWNER/REPOSITORY/projectsV2

```

Read a project, its items, and its fields:

```sh

openagents api repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER

openagents api repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/items

openagents api repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/fields

```

Create a repository project:

```sh

openagents api -X POST -f title="Release readiness" \

  repos/OWNER/REPOSITORY/projectsV2

```

Add an issue to a project. `issue_id` is the issue's numeric database ID from

the issue response, not its repository-local issue number:

```sh

printf '%s' '{"issue_id":42,"values":{"Status":"To Do"}}' | \

  openagents api -X POST --input - \

  repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/items

```

Update the stored values for an item:

```sh

printf '%s' '{"values":{"Status":"Done"}}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/items/ITEM_ID

```

## Use output in scripts

Standard output contains only a successful response body. `--json` writes the

same JSON on one line. Human diagnostics and failed API bodies go to standard

error.

```sh

openagents --json api repos/OWNER/REPOSITORY/issues >issues.json

```

A non-`2xx` response fails the command. The CLI includes the response's request

ID in the error when the server supplies one. Preserve that ID when you report

an API failure.

Do not parse human output from named repository commands as JSON. Add `--json`

to those commands. `openagents api` always returns the response body as JSON.

## Related documentation

- [CLI command reference](command-reference.md)

- [Install the CLI](install.md)

- [REST API assessment](../github-api-issues-projects-assessment.md)

# OpenAgents CLI command reference

The `openagents` command manages authentication and hosted repositories.

The `openagents` command manages authentication and hosted repositories. It

also sends authenticated requests to OpenAgents API routes that do not have a

named command yet.

```text

openagents <subcommand> [flags]

omit the repository, the CLI infers it from an exact OpenAgents `origin`

remote on the selected API origin.

## API command

```text

openagents api [flags] <path>

```

A path without a leading slash resolves under `/api/v3/`. For example,

`repos/OWNER/REPOSITORY/issues` and

`/api/v3/repos/OWNER/REPOSITORY/issues` name the same route. An absolute path

must start with `/api/` and stay on the selected API origin.

| Flag | Description |

| --- | --- |

| `--method METHOD`, `-X METHOD` | Use `GET`, `POST`, `PATCH`, `PUT`, or `DELETE`. The default is `GET`, or `POST` when the request has a body. |

| `--field KEY=VALUE`, `-f KEY=VALUE` | Add a repeatable string field to a JSON object body. |

| `--input FILE` | Read the complete JSON body from a file. Use `-` for standard input. |

| `--header 'NAME: VALUE'`, `-H 'NAME: VALUE'` | Add a repeatable request header. The CLI refuses an `Authorization` override. |

`--field` and `--input` are mutually exclusive. Use `--input` when a body

contains numbers, booleans, arrays, nested objects, or `null`; `--field` sends

every value as a JSON string.

```sh

openagents api repos/OWNER/REPOSITORY/issues

openagents api -X POST -f title="Search returns duplicates" \

  -f body="Steps to reproduce" \

  repos/OWNER/REPOSITORY/issues

printf '%s' '{"state":"closed","state_reason":"completed"}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/issues/41

```

The command writes a successful response body as JSON. A non-`2xx` response

writes the API error and request ID to standard error and exits with the

status-specific CLI exit code.

See [Call the API with the CLI](api.md) for Issues and Projects recipes and

the origin-boundary rules.

## JSON and noninteractive use

With `--json`, stdout contains machine-readable output. Human progress and

## Commands not included

This release does not provide `repo delete`, `repo mirror`, pull-request,

ruleset, SSH-key, generic API, or self-update commands. Use only commands shown

by the installed version's `--help` output.

This release does not provide named `issue` or `project` commands, repository

mirroring, pull-request commands, ruleset commands, SSH-key commands, or a

self-update command. Use `openagents api` for the implemented Issues and

Projects routes, and use only commands shown by the installed version's

`--help` output.

Pin the package version for a reproducible qualification run:

```sh

npx --yes @openagentsinc/cli@0.1.5 \

npx --yes @openagentsinc/cli@0.2.1 \

  --profile staging \

  repo import OWNER/REPOSITORY \

  --private \

1. Install the qualified CLI version:

   ```sh

   npm install --global @openagentsinc/cli@0.1.5

   npm install --global @openagentsinc/cli@0.2.1

   ```

2. Sign in to production and confirm the selected account:

The OpenAgents CLI (`openagents`) manages OpenAgents-hosted Git repositories

from a terminal. It uses the same repository API as the OpenAgents web

interface and leaves Git data transfer to standard Git.

interface, leaves Git data transfer to standard Git, and can call any

implemented API route.

The CLI is available from npm. OpenAgents qualified repository imports on

staging before deploying the same server revision to the production fleet.

```sh

npm install --global @openagentsinc/cli

npx --yes @openagentsinc/cli@latest --version

npx --yes @openagentsinc/cli@latest --help

```

Do not configure a persistent Git credential helper through `npx`. Install the

- Clone repositories and configure Git authentication.

- Delete a repository you own with explicit confirmation.

- Push, pull, and fetch through Git smart HTTP.

- Call Issues, Projects, and other implemented API routes with

  `openagents api`.

- Use JSON output and stable exit codes in scripts and agents.

Pull requests, continuous GitHub mirroring, SSH transport, rulesets, and

self-update are not part of this release.

Named `issue` and `project` commands, pull requests, continuous GitHub

mirroring, SSH transport, rulesets, and self-update are not part of this

release.

## Namespaces and access

- [Import a GitHub repository](import-github.md)

- [Clone, push, and pull](git.md)

- [Delete a repository](delete-repository.md)

- [Call the API](api.md)

- [CLI command reference](command-reference.md)

npm install --global @openagentsinc/cli

```

Verify the installed version:

Verify the installed npm package and command:

```sh

openagents --version

npm list --global @openagentsinc/cli --depth=0

openagents --help

```

`@openagentsinc/cli@0.2.1` contains an older embedded `--version` value and

reports `0.1.7`. Use the npm package listing to verify that release until a

later CLI release corrects the embedded value. Follow

[`OpenAgentsInc/openagents` issue 1](https://openagents.com/OpenAgentsInc/openagents/issues/1)

for the correction.

To update after a release, install the latest npm package again:

```sh

Use `npx` when you want to run one command without a global installation:

```sh

npx --yes @openagentsinc/cli@latest --version

npx --yes @openagentsinc/cli@latest --help

npx --yes @openagentsinc/cli@latest repo list

```

Pin a version for a reproducible run:

```sh

npx --yes @openagentsinc/cli@0.1.4 --version

npx --yes @openagentsinc/cli@0.2.1 --help

```

Place all CLI arguments after the package name:

- [Create a repository](create-repository.md)

- [Clone, push, and pull](git.md)

- [Call the API](api.md)

- [CLI command reference](command-reference.md)

          title: "CLI command reference",

          icon: "square-code",

          route: "/repositories"

        },

        %{

          slug: "cli-api",

          title: "Call the API with the CLI",

          icon: "square-code",

          route: "/api/v3/repos/:owner/:repo/issues"

        }

      ]

    },

# Call the API with the OpenAgents CLI

The `openagents api` command sends an authenticated request to any OpenAgents

API route and writes the response body as JSON. Use it for Issues, Projects,

and other routes that do not have a named CLI command.

The current release does not provide `openagents issue` or

`openagents project` commands. `openagents api` is the supported terminal path

for those resources.

## Before you begin

Install the CLI and sign in to the profile you intend to use:

```sh

npm install --global @openagentsinc/cli@latest

openagents auth login

openagents auth status

```

You can also set `OPENAGENTS_TOKEN` to an `oa_pat_` user token for one process.

The token must carry the authority required by the route.

## Address a route

A relative path resolves under `/api/v3/`:

```sh

openagents api repos/OWNER/REPOSITORY/issues

```

`repos/OWNER/REPOSITORY/issues` and

`/api/v3/repos/OWNER/REPOSITORY/issues` name the same route. An absolute path

must start with `/api/`. A complete URL must use the exact selected API origin.

The CLI refuses another origin and paths outside the API namespace.

## Select a method and body

Use `-X` or `--method` to select `GET`, `POST`, `PATCH`, `PUT`, or `DELETE`.

Without it, a request without a body uses `GET`, and a request with a body uses

`POST`.

Use repeatable `-f` or `--field` flags for string fields:

```sh

openagents api -X POST \

  -f title="Search returns duplicates" \

  -f body="Include steps to reproduce" \

  repos/OWNER/REPOSITORY/issues

```

Use `--input` for numbers, booleans, arrays, nested objects, or `null`:

```sh

printf '%s' '{"labels":["bug"],"milestone":3}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/issues/41

```

`--input` reads a file, or standard input when you pass `-`. `--field` and

`--input` are mutually exclusive. The CLI supplies the bearer credential and

refuses an `Authorization` header override.

## Work with issues

List issues. The response contains an `issues` array:

```sh

openagents api 'repos/OWNER/REPOSITORY/issues?state=all'

openagents api 'repos/OWNER/REPOSITORY/issues?state=all' | \

  jq -r '.issues[] | [.number, .state, .title] | @tsv'

```

Read, create, close, reopen, and comment on an issue:

```sh

openagents api repos/OWNER/REPOSITORY/issues/41

openagents api -X POST -f title="Search returns duplicates" \

  -f body="Steps to reproduce" \

  repos/OWNER/REPOSITORY/issues

printf '%s' '{"state":"closed","state_reason":"completed"}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/issues/41

openagents api -X PATCH -f state=open \

  repos/OWNER/REPOSITORY/issues/41

openagents api -X POST -f body="The fix is available in staging." \

  repos/OWNER/REPOSITORY/issues/41/comments

```

## Work with projects

List and read repository projects. The list response contains a `projects`

array:

```sh

openagents api repos/OWNER/REPOSITORY/projectsV2

openagents api repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER

openagents api repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/items

openagents api repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/fields

```

Create a project and add an issue. `issue_id` is the numeric database ID in the

issue response, not its repository-local issue number:

```sh

openagents api -X POST -f title="Release readiness" \

  repos/OWNER/REPOSITORY/projectsV2

printf '%s' '{"issue_id":42,"values":{"Status":"To Do"}}' | \

  openagents api -X POST --input - \

  repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/items

```

Update an item's values:

```sh

printf '%s' '{"values":{"Status":"Done"}}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/projectsV2/PROJECT_NUMBER/items/ITEM_ID

```

## Use output in scripts

Standard output contains only a successful response body. `--json` writes the

same JSON on one line. A non-`2xx` response fails the command and writes the API

error and request ID to standard error.

```sh

openagents --json api repos/OWNER/REPOSITORY/issues >issues.json

```

Preserve the request ID when you report a failed API call.

## Related documentation

- [REST API](/docs/rest-api)

- [API tokens](/docs/api-tokens)

- [CLI command reference](/docs/cli-command-reference)

# OpenAgents CLI command reference

The `openagents` command manages authentication and hosted repositories.

The `openagents` command manages authentication and hosted repositories. It

also sends authenticated requests to OpenAgents API routes that do not have a

named command yet.

```text

openagents <subcommand> [flags]

omit the repository, the CLI infers it from an exact OpenAgents `origin`

remote on the selected API origin.

## Call an API route

```text

openagents api [flags] <path>

```

A path without a leading slash resolves under `/api/v3/`. For example,

`repos/OWNER/REPOSITORY/issues` and

`/api/v3/repos/OWNER/REPOSITORY/issues` name the same route. An absolute path

must start with `/api/` and stay on the selected API origin.

| Flag | Description |

| --- | --- |

| `--method METHOD`, `-X METHOD` | Use `GET`, `POST`, `PATCH`, `PUT`, or `DELETE`. The default is `GET`, or `POST` when the request has a body. |

| `--field KEY=VALUE`, `-f KEY=VALUE` | Add a repeatable string field to a JSON object body. |

| `--input FILE` | Read the complete JSON body from a file. Use `-` for standard input. |

| `--header 'NAME: VALUE'`, `-H 'NAME: VALUE'` | Add a repeatable request header. The CLI refuses an `Authorization` override. |

Use `--input` when a body contains numbers, booleans, arrays, nested objects,

or `null`. `--field` sends every value as a JSON string. The two body options

are mutually exclusive.

```sh

openagents api repos/OWNER/REPOSITORY/issues

openagents api -X POST -f title="Search returns duplicates" \

  -f body="Steps to reproduce" \

  repos/OWNER/REPOSITORY/issues

printf '%s' '{"state":"closed","state_reason":"completed"}' | \

  openagents api -X PATCH --input - \

  repos/OWNER/REPOSITORY/issues/41

```

The command writes a successful response body as JSON. A non-`2xx` response

writes the API error and request ID to standard error and exits with the

status-specific CLI exit code.

See [Call the API with the CLI](/docs/cli-api) for Issues and Projects recipes.

## Use JSON in noninteractive processes

With `--json`, stdout contains machine-readable output. Human progress and

## Know which commands are unavailable

This release does not provide `repo delete`, `repo mirror`, pull-request,

ruleset, SSH-key, generic API, or self-update commands. Use only commands shown

by the installed version's `--help` output.

This release does not provide named `issue` or `project` commands, repository

mirroring, pull-request commands, ruleset commands, SSH-key commands, or a

self-update command. Use `openagents api` for the implemented Issues and

Projects routes, and use only commands shown by the installed version's

`--help` output.

## Next steps

- [Create a repository](/docs/create-repository)

- [Import from GitHub](/docs/import-github)

- [Clone, push, and pull](/docs/clone-push-pull)

- [Call the API with the CLI](/docs/cli-api)

Pin the package version for a reproducible qualification run:

```sh

npx --yes @openagentsinc/cli@0.1.5 \

npx --yes @openagentsinc/cli@0.2.1 \

  --profile staging \

  repo import OWNER/REPOSITORY \

  --private \

```sh

npm install --global @openagentsinc/cli

openagents --version

npm list --global @openagentsinc/cli --depth=0

openagents --help

```

`@openagentsinc/cli@0.2.1` contains an older embedded `--version` value and

reports `0.1.7`. Use the npm package listing to verify that release until a

later CLI release corrects the embedded value. Follow

[`OpenAgentsInc/openagents` issue 1](/OpenAgentsInc/openagents/issues/1) for the

correction.

Install the latest release again when you want to update:

```sh

globally: