@oxagen/cli 3.0.1-98 → 5.5.1-22

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 (3) hide show
  1. package/README.md +57 -22
  2. package/oxagen.mjs +117608 -82960
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -13,8 +13,8 @@ Full reference: **https://docs.oxagen.sh/docs/cli**
13
13
  ## Boundary
14
14
 
15
15
  - **Owns:** the `oxagen` command tree (`src/program.ts`), the browser login
16
- with PKCE and a loopback listener (`src/auth/`), the local config and
17
- workspace binding (`src/lib/config.ts`, `.oxagen/workspace.json`), the HTTP
16
+ with PKCE and a loopback listener (`src/auth/`), the local config and its
17
+ org and workspace selection (`src/lib/config.ts`), the HTTP
18
18
  client for the platform API (`src/lib/api.ts`), output formatting, and
19
19
  anonymous usage telemetry (`src/telemetry/usage.ts`).
20
20
  - **Does not own:** any capability logic. Every command that reads or changes
@@ -23,13 +23,10 @@ Full reference: **https://docs.oxagen.sh/docs/cli**
23
23
  commands (`oxagen agent enroll`, `oxagen agent run`, `oxagen hook`,
24
24
  `oxagen daemon`, and the rest), which lives in
25
25
  [`@oxagen/recorder`](../../packages/tacho/README.md) (`@oxagen/recorder/cli`),
26
- the steering freshness check
27
- ([`@oxagen/steering-freshness`](../../packages/steering-freshness/README.md)),
28
26
  or the consent page it opens (`/cli/authorize` in
29
27
  [`apps/app`](../app/README.md)).
30
28
  - **Depends on:** `@oxagen/recorder` (the machine commands under
31
- `oxagen agent`, and the hidden ones the hooks and the service run),
32
- `@oxagen/steering-freshness` (`oxagen steering`),
29
+ `oxagen agent`, and the hidden ones the hooks and the service run)
33
30
  and `@oxagen/billing` (`formatUsd` and the rate card from
34
31
  `@oxagen/billing/rate-card`, for display).
35
32
  - **Used by:** no workspace package imports it. It is published as the
@@ -43,7 +40,6 @@ Full reference: **https://docs.oxagen.sh/docs/cli**
43
40
  | Browser login (`/cli/authorize`, then `POST /v1/auth/cli/token`) | boundary | `apps/cli/src/auth/loopback-login.ts`, `pkce.ts` | `oxagen login` |
44
41
  | `CliDeps` from `defaultCliDeps` | adapter | `apps/cli/src/commands/tacho.ts` | `oxagen agent enroll`, `status`, `reassign`, `unenroll`, `export`, `verify`, `hosts`, `run`, and `detect`. The work lives in `@oxagen/recorder/cli` |
45
42
  | Machine command dispatch | adapter | `apps/cli/src/index.ts`, `apps/cli/src/machine/` | `oxagen hook`, `daemon`, `mcp-stdio`, `credential`, `github`, and `arp`, which go straight to the recorder before the command tree loads. Hidden from `oxagen --help` |
46
- | `evaluateGate`, `renderGate`, `installHook` | adapter | `apps/cli/src/commands/steering.ts` | `oxagen steering …`, and each harness's prompt-submit hook |
47
43
  | Usage telemetry (`POST /v1/telemetry/usage`) | boundary | `apps/cli/src/telemetry/usage.ts` | Every command, unless `oxagen telemetry off` or `DO_NOT_TRACK=1` |
48
44
 
49
45
  The CLI bootstraps no kernel gate and registers no handler. Contracts that
@@ -73,7 +69,7 @@ for the capability or a command file names it.
73
69
  ## Tests
74
70
 
75
71
  ```bash
76
- pnpm --filter @oxagen/cli test:unit src/commands/steering.test.ts
72
+ pnpm --filter @oxagen/cli test:unit src/commands/repo.test.ts
77
73
  ```
78
74
 
79
75
  Never put `--` before the filename. Tests live in `src/**/__tests__/` and
@@ -138,8 +134,8 @@ command for its flags. The full command tree lives in
138
134
  `apps/cli/src/program.ts` and is documented at
139
135
  https://docs.oxagen.sh/docs/cli/commands.
140
136
 
141
- Everything except `cost`, `logs`, `telemetry` and `codegraph` talks to the
142
- platform API and needs `oxagen login` first. `oxagen agent enroll` with a one-time enrollment
137
+ Everything except `cost`, `logs`, `telemetry` and the code graph commands
138
+ under `graph` talks to the platform API and needs `oxagen login` first. `oxagen agent enroll` with a one-time enrollment
143
139
  token needs no login either.
144
140
 
145
141
  **Meter and bill**
@@ -157,13 +153,11 @@ oxagen router preview|policy # the verified-outcome market router
157
153
  **Map the code:** the local code graph and CI upload
158
154
 
159
155
  ```bash
160
- oxagen codegraph init [path] # index a repo on this machine, watch it, and write the codegraph MCP entry
161
- oxagen codegraph init --embed-url http://127.0.0.1:11434/v1/embeddings # embed through a server on this machine
162
- oxagen codegraph init --scip # also build SCIP links
163
- oxagen codegraph status # each local graph with its pin, build state, and pending jobs
164
- oxagen codegraph rebuild [path] # build a fresh copy from the working tree
165
- oxagen codegraph stop [path] # stop watching and remove the MCP entries; --purge deletes the local tables
166
- oxagen codegraph upload --coverage "lcov=coverage/lcov.info" # CI: send coverage, reports, profiles, dumps, plans, and specs
156
+ oxagen graph init [path] # give each agent the oxagen MCP entry, then build the repo's code graph here
157
+ oxagen graph status # each local graph with its pin, build state, and base commit
158
+ oxagen graph rebuild [path] # build again, even when the working tree has not changed
159
+ oxagen graph stop # stop the local code graph server; --purge deletes every local graph
160
+ oxagen graph upload --coverage "lcov=coverage/lcov.info" # CI: send coverage, reports, profiles, dumps, plans, and specs
167
161
  ```
168
162
 
169
163
  `init` needs an enrolled machine. The local graph never leaves the machine.
@@ -173,6 +167,40 @@ needs no login. Its other flags are `--test-report`, `--runtime`,
173
167
  and `--fail-on-unconnected`. Each file flag takes `source=pattern` lines and
174
168
  can repeat. See https://docs.oxagen.sh/docs/cli/code-graph.
175
169
 
170
+ Use `oxagen graph` in scripts and CI jobs. The `oxagen codegraph` command has been removed.
171
+
172
+ ## MCP tools
173
+
174
+ Use the MCP commands to list, inspect, and call the tools the server ships.
175
+ They use the token saved by `oxagen login`, or `OXAGEN_API_TOKEN` when set.
176
+ The server applies the token's workspace scope and permissions to each call.
177
+
178
+ ```sh
179
+ oxagen mcp list
180
+ oxagen mcp describe send_work_item
181
+ oxagen mcp call list_work_items --input '{}'
182
+ oxagen mcp call send_work_item --input-file work-input.json
183
+ cat work-input.json | oxagen mcp call send_work_item --input-file -
184
+ ```
185
+
186
+ Each command prints JSON. `list` follows every page and includes the tool
187
+ schemas. `describe` prints the complete descriptor for one tool. `call`
188
+ prints the complete MCP result, including content and structured output.
189
+ A tool refusal or a connection or protocol error exits with a nonzero code.
190
+ The server validates arguments against the tool's schema.
191
+
192
+ Input defaults to `{}` and must be a JSON object. Use `--input-file` for
193
+ sensitive input so it stays out of shell history and the process list.
194
+ `--input` and `--input-file` cannot be combined.
195
+
196
+ The default endpoint is `https://mcp.oxagen.sh/mcp`. Use `--endpoint <url>`
197
+ only for a trusted MCP server: the CLI sends your token to that address.
198
+ The URL must use HTTPS without credentials, query parameters, or a fragment.
199
+ The CLI refuses redirects. `--timeout-ms <ms>` sets the deadline for the
200
+ connection and request, including all catalogue pages. The default is 60000
201
+ milliseconds and the maximum is 600000 milliseconds. A timed-out call may
202
+ have reached the server; inspect the affected record before retrying a write.
203
+
176
204
  **Explain:** runs and audit
177
205
 
178
206
  ```bash
@@ -190,8 +218,7 @@ oxagen memory list|show|promote|dismiss|import # the memories agents wrote in
190
218
  **Govern:** workspace, agents, credentials
191
219
 
192
220
  ```bash
193
- oxagen init --org <org> --workspace <ws> # link this project to an org + workspace
194
- oxagen pull # write the workspace's published steering into .oxagen/
221
+ oxagen init --org <org> --workspace <ws> # pick the org + workspace and report this directory
195
222
  oxagen steering import <paths...> # preview Markdown files as steering records and policies, then --yes opens the PR
196
223
  oxagen env list|get|create|update|rm|set-default # workspace environments
197
224
  oxagen secret list|set|rm|reveal|import|export # encrypted credential vault
@@ -208,12 +235,19 @@ oxagen agent verify --harness codex # one headless turn, confirmed
208
235
  oxagen agent run --name my-agent -- ./my-agent # one custom agent session under Oxagen
209
236
  oxagen agent detect # which harnesses this machine has
210
237
  oxagen agent reassign|unenroll|export|hosts # move, remove, export, list machines
238
+ oxagen agent export --session <id> --format recorder|trace|otlp
211
239
  ```
212
240
 
213
241
  `oxagen hook`, `oxagen daemon`, `oxagen mcp-stdio`, `oxagen credential`,
214
242
  `oxagen github`, and `oxagen arp` are hidden from help. The hooks, the user
215
243
  service, and the connected apps that enrollment installs run them.
216
244
 
245
+ The recorder also ships as its own `recorder` executable, with the same
246
+ commands. It was named `tacho` until #7501, and `tacho` still runs it. Typed
247
+ by a person under the old name, a command prints one warning line on stderr
248
+ that names the `recorder` command. `agent export --format` still takes
249
+ `tacho` and reads it as `recorder`.
250
+
217
251
  **Telemetry**
218
252
 
219
253
  ```bash
@@ -226,8 +260,9 @@ oxagen telemetry [on|off|status] # anonymous usage telemetry (on by default)
226
260
  oxagen login / logout
227
261
  ```
228
262
 
229
- The only project-local state the CLI writes is `.oxagen/workspace.json`, the
230
- org and workspace binding that `oxagen init` creates.
263
+ The CLI writes no file into a project. Its state lives under the home
264
+ directory, in `~/.config/oxagen/` and `~/.oxagen/`. A `.oxagen/workspace.json`
265
+ an earlier CLI wrote into a checkout is never read.
231
266
 
232
267
  ## Configuration
233
268
 
@@ -278,7 +313,7 @@ Other workflows:
278
313
  pnpm -C apps/cli dev -- graph search -q "workspace context" --limit 1
279
314
  pnpm -C apps/cli build # compile to dist/ once
280
315
  pnpm -C apps/cli bundle # standalone single-file bundle
281
- pnpm -C apps/cli test:unit src/commands/steering.test.ts # one file; CI runs the suite
316
+ pnpm -C apps/cli test:unit src/commands/repo.test.ts # one file; CI runs the suite
282
317
  pnpm -C apps/cli lint # lint (zero warnings enforced)
283
318
  pnpm -C apps/cli typecheck # type-check
284
319
  ```