---
name: onus-cli
description: Work with Onus issue tracking through the onus CLI — authenticate, fetch teams/projects/issues, create and update issues, manage comments, labels, relations, and attachments. Use when the user asks to find, list, create, update, comment on, or organize Onus issues, projects, or teams.
---

# Onus CLI

`onus` is the CLI for the Onus issue tracker. Always pass `--json` (or the global
`-j`) so output is machine-parseable JSON.

## Auth

```bash
onus auth login        # interactive OAuth login (stores token)
onus auth status       # check current auth state
ONUS_TOKEN=<token> onus me --json   # or auth via env var (ONUS_TOKEN / ONUS_API_KEY)
onus --token <token> me --json      # or per-invocation override
onus --api-url <url> …              # custom API base URL
```

## Golden rules

- **Starting work on an issue: transition it to `in_progress` immediately.** As soon as you pick up an issue to implement it — before writing any code — run `onus issue update <ref> --status in_progress --json`. No update needed if `onus issue get <ref> --json` already shows the status is `in_progress` or `done`.
- Add `--json` to every command you intend to parse.
- Whenever referencing an Onus issue in any response, include its link: `https://onus.brunyeestudio.com/team/{TEAM}/issues/{NUM}` where `{TEAM}` is the team key (the tag before the dash in the ref, e.g. `ONUS`) and `{NUM}` is the issue number (the number after the dash). Example: for ref `ONUS-1`, `TEAM = ONUS`, `NUM = 1` → https://onus.brunyeestudio.com/team/ONUS/issues/1
- Exit codes: `0` success · `1` general error · `2` validation error · `3` auth error · `4` not found.
- Issue commands take a `<ref>` = human identifier (e.g. `ENG-42`) or UUID. Every `--team <team>` option accepts a team KEY (e.g. `ONUS`) or a team UUID — prefer the KEY, it's stable and readable.
- List results paginate (`onus issue list` only): pass `--cursor <cursor>` from the previous response.
- Not sure what fields exist? Run `onus schema <resource>` (issue, project, team, comment, label) or `onus context` for an auth/capability snapshot.

## Discover resources

```bash
onus me --json                          # authenticated viewer profile
onus team list --json                   # teams you can see
onus team get ONUS --json               # by team KEY or UUID
onus project list --json                # projects across teams
onus label list --json                  # workspace labels (for --label ids)
```

## Find issues

```bash
onus issue list --json
onus issue list --team ONUS --status in_progress --json
onus issue list --assignee <userId> --project <projectId> --json
onus issue list --q "login bug" --limit 20 --json          # free-text search
onus issue list --cursor <cursor> --json                    # next page
onus issue get ENG-42 --json                                # single issue by ref
```

Status values: `backlog | todo | in_progress | done | canceled`.
Priority values: `none | urgent | high | medium | low`.

## Project agent context

Issues may belong to a project. A project's `agent_context` is its owner's
standing instructions for AI agents working on that project or its issues
(e.g. "add debug logging to all new implementations") — treat it as required
reading alongside the issue itself.

- Issue has a `project_id`? Fetch the project first
  (`onus project get <projectId> --json` → `.agent_context`) and follow it.
- Re-check `.agent_context` when moving an issue into/out of a project
  (`issue create/update --project`).
- Editing a project (name, status, description, `agent_context`) is
  permission-gated; never guess project UUIDs — `onus project list` first.
  Set context from a file: `onus project update <id> --agent-context-file AGENTS.md`.

## Create and update issues

```bash
onus issue create --title "Fix login redirect" --team ONUS \
  -d "Steps to reproduce: …" --status todo --priority high \
  --assignee <userId> --parent <parentIssueId> --label <labelId> --json

onus issue update ENG-42 --status in_progress --priority urgent --json
onus issue update ENG-42 --title "New title" -d "Updated body" --add-label <labelId> --json
onus issue update ENG-42 --remove-label <labelId> --assignee <userId> --json
onus issue delete ENG-42 --yes            # skip confirmation
```

## Comments

```bash
onus comment list ENG-42 --json
onus comment create ENG-42 --body "Root cause identified, fix incoming." --json
onus issue comment edit ENG-42 --comment <commentId> --body "Corrected my earlier analysis." --json
onus issue comment delete ENG-42 --comment <commentId>
```

(Top-level `comment` supports `list` and `create`; `issue comment` adds `edit`/`delete`.)

## Analytics

```bash
onus analytics overview --team ONUS --json
onus analytics overview --team ONUS \
  --from 2026-09-06T00:00:00+00:00 --to 2026-09-07T23:59:59+00:00 --json
onus analytics events --team ONUS --limit 25 --json
onus analytics query --team ONUS --query '{"type":"trends","series":[{"event":"signup"}]}' --json
```

## Relations, attachments, subscriptions

```bash
onus issue relation add ENG-42 --with ENG-43 --type blocks --json   # types: blocks|duplicate|related|similar
onus issue attachment upload ENG-42 --file ./notes.md --json
onus issue attachment list ENG-42 --json
onus issue subscribe ENG-42 --json
onus issue link-pr ENG-42 --repo owner/repo --pr 42 --json    # link a GitHub pull request
```

## Errors and ingest keys (DSN)

```bash
onus dsn list --team ONUS --json          # masked ingest keys for a team
onus dsn create --team ONUS --label ci    # prints the full secret exactly once
```

## Pull requests and issues

Linking a PR to an issue means **the issue is auto-closed when the PR merges** —
there is no "related" link type. How links are created:

- **Auto-linking is GitHub-style.** The integration scans the PR title, body,
  and branch name for `KEY-123` refs introduced by a closing keyword —
  `Fixes` / `Closes` / `Resolves` (case-insensitive, optional colon, comma/
  `and` lists). A plain prose mention of an issue ID does NOT link and never
  auto-closes, so avoid writing bare issue IDs in PR text: use the issue's
  name or its Onus URL instead.
- **Manual linking is deliberate.** `onus issue link-pr` creates a bot link
  that survives body edits and closes on merge — use it when the PR fully
  resolves an issue but its text has no closing keyword.
- **Only link PRs that actually fix/close the issue.** If a PR merely touches
  related code, discusses the issue, or implements part of it without completing
  it, do NOT link it (no keyword in the PR text, no `link-pr`). Use a relation
  (`onus issue relation add … --type related`) or a comment mention instead.
- Never guess or assume: before linking, verify the PR's changes fully resolve
  the issue (e.g. you implemented the fix in that PR, or the PR description
  says "Fixes ONUS-42").
- Link at most once per PR per issue; don't spam links across partially-related
  issues.

Run any command with `--help` for its exact flags — e.g. `onus issue relation add --help`.