@anyforge/control 0.2.4 → 0.4.0

package/README.md

@@ -1,6 +1,11 @@
 # @anyforge/control
 
-Governed LLM proxy for any agent. Use the AI tools you already use — Claude Code, Cursor, Cline, Continue, or your own SDK — and route every call through AnyForge for cost analytics, audit log, and policy enforcement.
+Two things in one binary:
+
+1. **A governed LLM proxy** for any agent — Claude Code, Cursor, Cline, Continue, or your own SDK. Route their calls through AnyForge for cost analytics, audit log, and policy enforcement.
+2. **A scriptable AnyForge client** — approvals, crews, work items and workflows from a shell, with no browser and no agent in the loop.
+
+The second half is what makes AnyForge usable from CI. Every command speaks the same `/api/v1/control/*` API the MCP server does, but without needing a language model to drive it.
 
 ## Install
 
@@ -50,12 +55,70 @@ Claude Code recognises both, but they behave differently. `ANTHROPIC_API_KEY` is
 
 ## Commands
 
+### Setup
+
 | | |
 |---|---|
 | `anyforge init` | Authorise this device and patch local agent configs |
-| `anyforge whoami` | Show the company tied to the saved key |
+| `anyforge whoami` | Show the company, scopes and endpoint this key acts as (asks the server) |
 | `anyforge status` | Verify the proxy is reachable and your BYOK key is configured |
 | `anyforge logout` | Clear the local credential file **and revert patched configs** (does not revoke server-side) |
+| `anyforge apply-patch` | Apply a unified diff from a file or stdin via `git apply` |
+
+### Scriptable
+
+| | | Scope |
+|---|---|---|
+| `anyforge approvals` | List HIL approvals awaiting a decision | `read` |
+| `anyforge approve <id>` | Approve one (`--notes` is recorded in the audit trail) | `approve` |
+| `anyforge reject <id>` | Reject one | `approve` |
+| `anyforge crews` | List crews (`--active` for non-terminal only) | `read` |
+| `anyforge crew <id>` | Show one crew, its status and recent output | `read` |
+| `anyforge crew start <item>` | Dispatch a crew on a work item (`--profile`, `--follow`) | `write` + a role that can dispatch |
+| `anyforge crew follow <id>` | Watch a run until it needs a person or ends (`--interval`) | `read` |
+| `anyforge halt <id>` / `resume <id>` | Stop or restart a crew | `approve` |
+| `anyforge work` | List work items (`--status`, `--type`, `--priority`, `--search`, …) | `read` |
+| `anyforge workflows` | List operator workflows | `read` |
+| `anyforge run <id>` | Dispatch a run (`--input '{"repo":"acme/web"}'`) | `write` |
+| `anyforge ask <question>` | Ask the Oracle one question | `read` |
+
+Every command takes `--json`, which prints the API payload verbatim:
+
+```bash
+anyforge approvals --json | jq 'length'
+anyforge crews --active --json | jq -r '.[].id' | xargs -n1 anyforge halt
+```
+
+### Exit codes
+
+CI gates on these, so they are a contract:
+
+| | |
+|---|---|
+| `0` | Success — an empty list included |
+| `1` | Network or unexpected failure (retryable) — and a `crew follow` whose run ended `HALTED` / `REJECTED` / `CANCELLED`, which is not |
+| `2` | Usage error |
+| `3` | Not authenticated — run `init`, or set `ANYFORGE_API_TOKEN` |
+| `4` | The API refused; its error code prints to stderr |
+
+Errors and progress go to stderr, so a `--json` pipe stays parseable under a failure.
+
+`crew follow` is the one command whose exit code carries an OUTCOME rather than
+a transport result, which is what makes it usable as the last step of a job:
+
+```bash
+# Hand a ticket to a crew and fail the build if the work didn't land.
+anyforge crew start "$ITEM" --follow
+```
+
+It exits `0` when the run finishes or stops at a gate that needs a person, and
+`1` when the run ended badly or was still going after 30 minutes. Under `--json`
+its final line is `{ crewId, status, waiting, url }`, so a script can tell those
+two `0`s apart.
+
+### Unattended use
+
+Set `ANYFORGE_API_TOKEN` (and optionally `ANYFORGE_API_URL`) instead of running `init` — no browser, no credential file. Mint the key under **Settings → API keys** with the narrowest scope the job needs.
 
 ## Endpoints
 
@@ -63,8 +126,8 @@ The CLI defaults to `https://crew.anyforge.ai`. Override per-invocation with `--
 
 The proxy exposes:
 
-- `POST /v1/anthropic/messages` — drop-in for `https://api.anthropic.com/v1/messages`. Use `Authorization: Bearer sk_anyforge_…` instead of `x-api-key`.
-- `POST /v1/openai/chat/completions` — drop-in for `https://api.openai.com/v1/chat/completions`.
+- `POST /v1/anthropic/v1/messages` — drop-in for `https://api.anthropic.com/v1/messages`. Use `Authorization: Bearer sk_anyforge_…` instead of `x-api-key`. The `/v1` repeats because you set `ANTHROPIC_BASE_URL` to `https://crew.anyforge.ai/v1/anthropic` and the Anthropic SDK appends `/v1/messages` to it.
+- `POST /v1/openai/v1/chat/completions` — drop-in for `https://api.openai.com/v1/chat/completions`.
 
 Both validate your AnyForge API key, look up your company's BYOK provider key, forward the request, and stream the response back unchanged. Token counts and cost are logged to your usage dashboard.