@invarn/cli 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# invarn
+
+Run builds, check artifacts, and ship from your terminal — with a built-in MCP server so AI agents (Claude Code, Cursor, Claude Desktop) can drive your CI from inside a conversation.
+
+## Install
+
+```bash
+npm install -g @invarn/cli
+```
+
+This installs the `invarn` command.
+
+## Getting Started
+
+### 1. Authenticate
+
+```bash
+invarn auth login                   # Browser-based (recommended)
+invarn auth login --device-auth     # Device code (headless/SSH)
+invarn auth login --token inv_human_...   # Direct token from the dashboard
+```
+
+The token is stored in `~/.config/invarn/config.json`. Check status any time with `invarn auth status`.
+
+### 2. Run a build
+
+```bash
+# Submit a build on Invarn's infrastructure
+invarn build run --pipeline .ci/pipelines/cibuild.yml --workflow primary
+
+# Or run a local-* pipeline on your own machine (via @invarn/cibuild)
+invarn run --pipeline .ci/pipelines/agent-verify.yml --workflow test
+```
+
+### 3. Let AI drive your CI
+
+Start the MCP server and your AI coding agent can register agents, run builds, and report results without leaving the conversation:
+
+```bash
+invarn mcp serve
+```
+
+Add it to Claude Code via `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "invarn": {
+      "command": "invarn",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `invarn auth login` | Authenticate via browser (PKCE) |
+| `invarn auth login --device-auth` | Authenticate via device code (headless) |
+| `invarn auth login --token <token>` | Authenticate with a token directly |
+| `invarn auth logout` | Remove stored credentials |
+| `invarn auth status` | Show current auth state |
+| `invarn build run --pipeline <path> --workflow <name>` | Submit a new proof |
+| `invarn build list [--state <s>]` | List recent proofs |
+| `invarn build status <build-id>` | Show proof details |
+| `invarn build logs <build-id>` | Stream proof logs |
+| `invarn build cancel <build-id>` | Cancel a running proof |
+| `invarn build retry <build-id>` | Retry a failed proof |
+| `invarn artifact list <build-id>` | List artifacts for a proof |
+| `invarn artifact download <build-id> [--out <dir>]` | Download artifact bundle |
+| `invarn secrets list [--pipeline <id>]` | List secrets at org or pipeline scope |
+| `invarn secrets set <KEY> [--pipeline <id>]` | Create or update a secret (stdin-only) |
+| `invarn secrets rm <KEY> [--pipeline <id>]` | Delete a secret |
+| `invarn vars list/set/rm` | Same as `secrets` for plaintext variables |
+| `invarn run --pipeline <path> [--workflow <name>]` | Run a local-* pipeline on this machine |
+| `invarn mcp serve` | Start MCP server for AI agents |
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON |
+| `--no-follow` | Don't follow logs (snapshot only) |
+| `--out <dir>` | Output directory for downloads |
+
+## Local pipelines
+
+Pipelines with `stack: local` run on your own machine via the embedded [`@invarn/cibuild`](https://www.npmjs.com/package/@invarn/cibuild) engine — no remote runner, no network round trip. Useful for fast iteration and for AI agents that need to verify changes before a push.
+
+```yaml
+# .ci/pipelines/agent-verify.yml
+format_version: '1'
+meta:
+  cibuild.io:
+    stack: local
+workflows:
+  test:
+    steps:
+      - script@1.0.0:
+          inputs:
+            content: npm ci && npm test
+```
+
+```bash
+invarn run --pipeline .ci/pipelines/agent-verify.yml --workflow test
+```
+
+## MCP server (for AI agents)
+
+`invarn mcp serve` exposes build, artifact, secret, and agent operations as MCP tools:
+
+| Tool | Description |
+|---|---|
+| `invarn_agent_find` | Search for an existing agent by intent/type |
+| `invarn_agent_register` | Register a new AI agent with its own pipeline |
+| `invarn_agent_list` | List all agents in the organization |
+| `invarn_agent_unregister` | Delete an agent |
+| `invarn_agent_run` | Run a workflow through an agent (local or remote) |
+| `invarn_agent_result` | Fetch build state, step progress, logs, artifacts |
+| `invarn_build_list` | List recent builds |
+| `invarn_build_logs` | Fetch log output for a build |
+| `invarn_build_cancel` | Cancel a running build |
+| `invarn_build_retry` | Retry a failed build |
+| `invarn_artifact_list` | List artifacts for a build |
+| `invarn_secrets_list` | List secret/variable metadata (never values) |
+| `invarn_secrets_set` | Create or update a secret or variable |
+
+Agents are AI-owned pipelines — created on demand by an orchestrator, invoked by AI, and reported back into the conversation. Each agent has its own credentials, its own pipeline file, and short-lived session tokens scoped to one human user.
+
+## Secrets
+
+Secrets and variables are scoped to the org or a specific pipeline. Values are piped via stdin — never passed on argv (visible in shell history and `ps` output):
+
+```bash
+echo "sk_live_..." | invarn secrets set STRIPE_KEY
+echo "sk_live_..." | invarn secrets set STRIPE_KEY --pipeline pipe_abc
+invarn secrets list
+invarn secrets rm STRIPE_KEY
+```
+
+There is no read command — once set, values cannot be retrieved through the CLI or MCP.
+
+## Requirements
+
+- Node.js 22+
+- A registered Invarn organization (sign up at [invarn.com](https://invarn.com))