@brunyee-studio/onus-cli 2.30.0 → 2.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunyee-studio/onus-cli",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "description": "Official CLI and TypeScript SDK for Onus issue tracking platform",
   "keywords": [
     "agent",

package/skills/onus-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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, and consult the knowledge base (kb). Use when the user asks to find, list, create, update, comment on, or organize Onus issues, projects, or teams, or to read KB docs.
 ---
 
 # Onus CLI
@@ -16,11 +16,17 @@ 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
+onus auth logout       # clear stored credentials
 ```
 
+Explicit token overrides (`--token` or `ONUS_TOKEN` / `ONUS_API_KEY`) take
+precedence over stored credentials and **fail hard with exit 3** when the API
+rejects them — they are never silently rescued by the stored session.
+Transparent refresh on 401 applies only to the stored config-file session.
+
 ## 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`.
+- **Starting work on an issue: transition it to `in_progress` and make sure it has an owner — you.** As soon as you pick up an issue to implement it — before writing any code — resolve your user id (`onus me --json` → `.id`), then run `onus issue update <ref> --status in_progress --assignee <userId> --json`. Self-assign only when the issue is unassigned or already assigned to you; if someone else is the assignee, leave them in place and say so. No update needed if `onus issue get <ref> --json` already shows the status is `in_progress` or `done` — but if it is `in_progress` while unassigned, still assign it to yourself.
 - Add `--json` to every command you intend to parse.
 - Multi-line text (issue descriptions, comment bodies, agent context) goes through the field's file flag — `--description-file`, `--body-file`, `--agent-context-file` — never inline in the shell command. See "Long text via file input" below.
 - 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
@@ -44,8 +50,10 @@ onus label list --json                  # workspace labels (for --label ids)
 ```bash
 onus issue list --json
 onus issue list --team ONUS --status in_progress --json
+onus issue list --priority high --team ONUS --json          # filter by priority
 onus issue list --assignee <userId> --project <projectId> --json
 onus issue list --q "login bug" --limit 20 --json          # free-text search
+onus issue list --q ONUS-42 --json                          # display-key search
 onus issue list --cursor <cursor> --json                    # next page
 onus issue get ENG-42 --json                                # single issue by ref
 ```
@@ -82,6 +90,38 @@ onus issue update ENG-42 --remove-label <labelId> --assignee <userId> --json
 onus issue delete ENG-42 --yes            # skip confirmation
 ```
 
+## Templates
+
+Per-team reusable issue templates; `--default` marks a team's default:
+
+```bash
+onus template list --team ONUS --json
+onus template create --team ONUS --name "Bug report" --priority high --default --json
+onus template get <id> --json
+onus template update <id> --title "New title" --add-label <labelId> --json   # alias: template edit
+onus template delete <id> --yes
+```
+
+`onus issue create --template <nameOrId>` fills omitted fields from the template.
+
+## Bulk operations
+
+`issue bulk-update` / `issue bulk-comment` apply to many issues with per-item partial success:
+
+```bash
+onus issue bulk-update ENG-42 ENG-43 --status done --json
+onus issue bulk-comment ENG-42 ENG-43 --body "Deployed in v2.31" --idempotency-key run-17 --json
+onus issue bulk-update --file ./items.json --json   # per-item payloads; see --help for the format
+```
+
+## Create projects
+
+```bash
+onus project create --name "Mobile app" --team ONUS --lead <userId> \
+  --description-file ./brief.md --agent-context-file AGENTS.md --json
+onus project attachment list <projectId> --json
+```
+
 ## Long text via file input
 
 Multi-line values (issue and project descriptions, comment bodies, project
@@ -125,14 +165,28 @@ onus analytics events --team ONUS --limit 25 --json
 onus analytics query --team ONUS --query '{"type":"trends","series":[{"event":"signup"}]}' --json
 ```
 
+## Watch (live events)
+
+```bash
+onus watch --team ONUS --type issue.status_changed,error_group.regressed --json
+```
+
+Streams live issue/comment/error events over SSE with automatic resume.
+
 ## 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 relation remove ENG-42 --relation <relationId> --json
+onus issue attachment upload ENG-42 --file ./notes.md --json
 onus issue attachment list ENG-42 --json
+onus issue attachment download ENG-42 --attachment <attachmentId> --output ./notes.md --json
+onus issue attachment delete ENG-42 --attachment <attachmentId> --json
 onus issue subscribe ENG-42 --json
+onus issue unsubscribe ENG-42 --json
 onus issue link-pr ENG-42 --repo owner/repo --pr 42 --json    # link a GitHub pull request
+onus issue unlink-pr ENG-42 --pr-link <linkId> --json         # remove a linked pull request
 ```
 
 ## Errors and ingest keys (DSN)
@@ -140,8 +194,33 @@ onus issue link-pr ENG-42 --repo owner/repo --pr 42 --json    # link a GitHub pu
 ```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
+onus dsn rotate <keyId> --grace-seconds 86400 --json   # old secret stays valid during the grace window
+onus dsn disable <keyId> --json           # reversible
+onus dsn enable <keyId> --json            # re-enable a disabled key
+onus dsn revoke <keyId> --json            # terminal
+```
+
+## Knowledge base (agent workflow)
+
+Consult the KB before implementing an issue — docs (`index | area | process |
+incident` kinds) describe code areas, processes, and incidents. Read-only: no
+CLI command or API mutates docs.
+
+```bash
+onus kb locate --issue <issueUuid> --json   # locate first, on issue start (or --query "text"; exactly one)
+onus kb get <slug> --json                    # then read each returned doc (also accepts UUID; ambiguous slug → exit 2)
+onus kb search "<query>" --json              # scored search; --mode string|semantic|hybrid|related (--doc <slug> required with related)
+onus kb related <slug> --json                # expand related docs
+onus kb list --team ONUS --kind area --tag auth --limit 20 --cursor <cursor> --json
 ```
 
+- Results carry staleness `{stale, confidence, reason}` — a `stale` doc is
+  planning input: verify it against current code and surface drift.
+- **Surface drift, never write it.** Note stale/incorrect docs in the PR
+  description ("KB drift: …"); regeneration is infrastructure-led on merge —
+  the pipeline updates affected docs automatically after the PR merges
+  (human-edited docs get proposed revisions for human approval).
+
 ## Pull requests and issues
 
 Linking a PR to an issue means **the issue is auto-closed when the PR merges** —
@@ -176,4 +255,19 @@ Required PR flow, in order:
 - Link at most once per PR per issue; don't spam links across partially-related
   issues.
 
+## Skill management
+
+The CLI bundles this skill and can install/update it for detected AI agents:
+
+```bash
+onus skill install --agent claude-code codex   # or --global / --copy; see --help
+onus skill update                              # refresh installed copies to the bundled version
+onus skill remove --global                     # alias: skill rm
+```
+
+## Command aliases
+
+`issue get` = `issue view`, `issue update` = `issue edit`, `template update` = `template edit`,
+`skill remove` = `skill rm`.
+
 Run any command with `--help` for its exact flags — e.g. `onus issue relation add --help`.