@magnetoagents/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magneto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# magneto CLI
+
+Thin Node CLI for Magneto's public programmatic API (`/api/v1`) using workspace `sk_live_*` keys. Same surface as the Agent Skill and hosted MCP — no private endpoints, no session cookies. This is the docs' copy-paste reference client.
+
+Published as **`@magnetoagents/cli`**. The installed command is **`magneto`**.
+
+## Install
+
+| Method | Command |
+|--------|---------|
+| npm (global) | `npm install -g @magnetoagents/cli` |
+| npx | `npx @magnetoagents/cli` |
+| from-source | `cd app/cli && npm ci && npm run build` then `node dist/cli.js` / `npm link` |
+
+The first registry publish waits on the `@magneto` npm org + `NPM_TOKEN` repo secret. Until then, use from-source.
+
+## Quickstart
+
+About 90 seconds after you have an `sk_live_*` key (mint in the dashboard):
+
+```bash
+npx @magnetoagents/cli login sk_live_…
+npx @magnetoagents/cli computers list
+```
+
+From-source, after `npm ci && npm run build` in `app/cli`:
+
+```bash
+export MAGNETO_API_BASE=http://localhost:${FRONTEND_PORT:-3000}   # omit for production
+node dist/cli.js login sk_live_…
+node dist/cli.js computers list
+```
+
+This quickstart only lists. Do not `create` or `delete` unless you mean it.
+
+## Versioning (v0.x)
+
+Bump `package.json` `version` by hand (patch = fix, minor = additive or breaking while major is 0). `magneto --version` reads that field at runtime. Publish is `workflow_dispatch` on `.github/workflows/npm-publish.yml`, not a git tag.
+
+## Auth
+
+```bash
+magneto login sk_live_…
+# writes ~/.magneto/credentials.json (mode 0600), dir 0700
+```
+
+Resolution order:
+
+1. `MAGNETO_API_KEY` environment variable
+2. `~/.magneto/credentials.json` → `{ "api_key": "sk_live_…" }`
+
+## Base URL
+
+| Env | Default |
+|-----|---------|
+| `MAGNETO_API_BASE` or `MAGNETO_BASE_URL` | `https://magnetoapp.io` (client appends `/api/v1`) |
+| `MAGNETO_TIMEOUT_MS` | `30000` (JSON requests only; streams and signed-URL downloads are exempt) |
+
+Local / worktree:
+
+```bash
+export MAGNETO_API_BASE=http://localhost:${FRONTEND_PORT:-3000}
+# worktree ports often come from repo `.ports.env`
+```
+
+The client retries **once** on HTTP 429, honoring `Retry-After` (delta-seconds or HTTP-date, capped at 60s).
+
+## Commands
+
+```bash
+magneto login <key>
+
+magneto computers list [--output table|json|quiet]
+magneto computers get <id> [--output table|json|quiet]
+magneto computers create [--name NAME] [--flavor agent|desktop] [--template-id N] [--vcpu N] [--ram-gb N] [--disk-gb N]
+magneto computers start <id>
+magneto computers stop <id>
+magneto computers restart <id>
+magneto computers resize <id> --vcpu N --ram-gb N --disk-gb N
+magneto computers delete <id> --confirm <name>   # irreversible; name must match
+magneto computers uptime <id> [--window-seconds N] [--output table|json|quiet]
+
+magneto gateway <id> --target desktop|terminal [--open]
+# prints a 60-second signed URL to stdout. Do not write it to shell history or logs.
+
+magneto run "Open a browser" --computer <id> [--model …] [--max-steps N]
+magneto runs list --computer <id> [--limit N] [--offset N] [--output table|json|quiet]
+magneto runs get <run_id> --computer <id> [--output table|json|quiet]
+magneto runs export <run_id> --computer <id> [-o file]
+magneto runs stop <run_id> --computer <id>
+
+magneto bash <id> -- "cmd with spaces" [--timeout 60]
+# requires scope `exec` (not in the default key set)
+
+magneto files list [--output table|json|quiet]
+magneto files upload <path>
+magneto files download <id> [-o dir/]
+
+magneto templates list [--skip N] [--limit N] [--output table|json|quiet]
+magneto skills search [query] [--skip N] [--limit N] [--output table|json|quiet]
+# search is client-side over the fetched page; v1 has no ?q=.
+magneto skills install <skill_id> --computer <id>
+magneto skills uninstall <skill_id> --computer <id>
+
+magneto account [--output table|json|quiet]
+```
+
+## Output formats
+
+`--output` is the long flag only (no `-o` alias). `-o` is the path flag on `runs export` and `files download`.
+
+| Value | Meaning |
+|-------|---------|
+| `table` | Fixed-width columns (no TUI deps). Empty list prints `(none)`. |
+| `json` | Pretty-printed raw response |
+| `quiet` | One id per line |
+
+When `--output` is omitted: **table** if stdout is a TTY, **json** if piped (so existing `jq` one-liners keep working). An explicit `--output` always wins.
+
+Mutations (`create`, `start`, `stop`, `restart`, `resize`, `delete`, `skills install`/`uninstall`, `runs stop`, `files upload`) still print pretty JSON of the response (204 → silent / `ok`).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | API or client error (including 402 / 404 / 409 / 422 / 429-after-retry / 5xx / timeout / missing key) |
+| `2` | HTTP 401 or 403 |
+| `N` | `magneto bash` only: remote `exit_code` on HTTP 200 (`N & 255`) |
+
+Error lines look like:
+
+```
+error: <detail> (HTTP <status>) · request-id: <id> · Retry-After: <n>
+```
+
+`request-id` / `Retry-After` segments are omitted when the server did not send them.
+
+## Scopes
+
+Keys are minted in the dashboard. Default scopes do **not** include `exec`.
+
+| Command | Required scope |
+|---------|----------------|
+| `computers *`, `gateway`, `skills install`, `skills uninstall` | `computers` |
+| `run`, `runs *` | `runs` |
+| `bash` | **`exec`** (opt-in, not default) |
+| `files *` | `files` |
+| `templates list`, `skills search` | `catalog` |
+| `account` | `account` |
+| `login` | (none — writes the key locally) |
+
+A key without `exec` fails `magneto bash` with HTTP 403 `Missing scope: exec` and exit 2.
+
+## Notes
+
+- **Gateway URL** is a 60-second credential. It is printed to stdout only. `--open` launches the default browser (`open` / `xdg-open` / `cmd /c start`). Do not write the URL to shell history files or logs.
+- **`computers delete --confirm <name>`** is irreversible deprovision. The name must match the computer; there is no interactive prompt.
+- **`skills search [query]`** always calls `GET /api/v1/skills?skip=&limit=`. A query filters that page client-side (case-insensitive substring on `name` + `description`). v1 has no `?q=`.
+
+## Live smoke
+
+Verification lane (`BACKEND_PORT=8020 FRONTEND_PORT=3020 ./scripts/start.sh`). Mint a key with `exec` if you want `bash` to succeed.
+
+```bash
+export MAGNETO_API_BASE=http://localhost:${FRONTEND_PORT:-3020}
+export MAGNETO_API_KEY=sk_live_…
+cd app/cli
+npx magneto login "$MAGNETO_API_KEY"
+npx magneto computers create --name cli-440 --flavor desktop --vcpu 2 --ram-gb 4 --disk-gb 32
+ID=…  # from --output json / quiet
+npx magneto computers uptime "$ID"
+npx magneto bash "$ID" -- "echo ok"
+npx magneto run "Open a browser" --computer "$ID"
+npx magneto runs list --computer "$ID"
+npx magneto runs export "$RUN_ID" --computer "$ID" -o /tmp/run-440.json
+npx magneto files upload ./README.md
+npx magneto files download "$FILE_ID" -o /tmp/
+npx magneto computers delete "$ID" --confirm cli-440
+```
+
+After revoke in the dashboard, `computers list` should exit 2 with HTTP 403 `API key revoked`.
+
+## Related surfaces
+
+- Agent Skill: `https://magnetoapp.io/skills/computer/SKILL.md`
+- Hosted MCP: `https://magnetoapp.io/mcp` (Bearer key)
+- Stdio package: `packages/mcp` (`@magnetoagents/mcp`)
+
+All three consume Worker `/api/v1` + `requireApiKey` (#388 / #110 / #440).

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export type CliIo = {
+    fetchImpl?: typeof fetch;
+    stdout?: {
+        write(s: string | Uint8Array): void;
+        isTTY?: boolean;
+    };
+    stderr?: {
+        write(s: string): void;
+    };
+    exit?: (code: number) => never;
+    openUrl?: (url: string) => Promise<void>;
+    env?: NodeJS.ProcessEnv;
+};
+/** Thrown by injected `io.exit` in tests so action `catch` blocks do not remap the code to 1. */
+export declare class CliExitError extends Error {
+    readonly exitCode: number;
+    constructor(exitCode: number);
+}
+export declare function handleError(err: unknown, io?: CliIo): never;
+export declare function buildProgram(io?: CliIo): Command;