@blinkdotnew/cli 0.1.1

package/AGENTS.md

@@ -0,0 +1,291 @@
+# @blinkdotnew/cli — Blink Platform CLI
+
+The unified CLI for the Blink platform. Pre-installed in every Blink Claw agent (Fly.io machine). Also usable by developers for CI/CD and "Deploy to Blink" workflows.
+
+```bash
+npx @blinkdotnew/cli deploy          # human use
+blink deploy proj_xxx ./dist --prod  # agent use (zero config — env vars already set)
+```
+
+---
+
+## ⚠️ Critical: Two Backends, Never Mix
+
+Every command routes to one of two backends. **Wrong backend = silent failure or wrong data.**
+
+| Backend | Env var | Default | Owns |
+|---|---|---|---|
+| `blink.new` (auto-engineer, Next.js) | `BLINK_APP_URL` | `https://blink.new` | Deploy, project CRUD, logs, env vars, auth |
+| `core.blink.new` (blink-apis, Express) | `BLINK_APIS_URL` | `https://core.blink.new` | DB, storage, AI, realtime, RAG, notify, connectors |
+
+**Rule**: hosting/project/deploy → `BLINK_APP_URL`. Resources/AI/data → `BLINK_APIS_URL`.
+
+In code: `src/lib/api-app.ts` → blink.new, `src/lib/api-resources.ts` → core.blink.new.  
+`x-blink-agent-id` header is sent **only** on `api-resources.ts` calls (for per-agent billing).
+
+---
+
+## Package Structure
+
+```
+packages/cli/
+├── src/
+│   ├── cli.ts                  # Entry point — registers all command groups
+│   ├── commands/
+│   │   ├── ai.ts               # blink ai image/video/animate/speech/transcribe/text → core.blink.new
+│   │   ├── auth.ts             # blink login/logout/whoami                          → blink.new
+│   │   ├── connector.ts        # blink connector exec                               → core.blink.new
+│   │   ├── db.ts               # blink db query/exec/list                           → core.blink.new
+│   │   ├── deploy.ts           # blink deploy / deployments / rollback              → blink.new
+│   │   ├── notify.ts           # blink notify email                                 → core.blink.new
+│   │   ├── project.ts          # blink project / blink link / blink status          → blink.new
+│   │   ├── rag.ts              # blink rag search/upload/collections                → core.blink.new
+│   │   ├── realtime.ts         # blink realtime publish                             → core.blink.new
+│   │   ├── storage.ts          # blink storage upload/download/list/delete/url      → core.blink.new
+│   │   └── web.ts              # blink fetch / blink search                         → core.blink.new
+│   └── lib/
+│       ├── api-app.ts          # HTTP client → BLINK_APP_URL (blink.new)
+│       ├── api-resources.ts    # HTTP client → BLINK_APIS_URL (core.blink.new) + x-blink-agent-id
+│       ├── auth.ts             # Token resolution: --token flag > BLINK_API_KEY env > config file
+│       ├── config.ts           # Read/write ~/.config/blink/config.toml
+│       ├── output.ts           # chalk colors, ora spinners, cli-table3 tables, --json mode
+│       └── project.ts          # Read/write .blink/project.json, resolveProjectId()
+├── dist/cli.js                 # Built ESM bundle (~40KB), shebang prepended by tsup
+├── package.json                # name: @blinkdotnew/cli, bin: { blink: ./dist/cli.js }
+└── tsup.config.ts              # banner: #!/usr/bin/env node, no splitting
+```
+
+---
+
+## Full Command Reference
+
+### Auth (→ blink.new)
+```bash
+blink login                       # Browser OAuth (Phase 2) or no-op if BLINK_API_KEY set
+blink login --interactive         # Prompt for API key — for headless/SSH
+blink logout                      # Remove ~/.config/blink/config.toml entry
+blink whoami                      # Show current user + workspace
+```
+
+### Project (→ blink.new)
+```bash
+blink link [project_id]           # Interactive picker or direct link → writes .blink/project.json
+blink unlink                      # Remove .blink/project.json
+blink status                      # Show linked project + auth source
+blink project list
+blink project create <name>
+blink project delete <project_id> [--yes]
+```
+
+### Deploy (→ blink.new)
+```bash
+blink deploy [project] [dir]      # Upload pre-built output dir to Blink hosting
+blink deploy --prod               # Promote to production domain
+blink deploy --preview            # Preview deployment (default)
+blink deployments [project]       # List deployments
+blink rollback [project] [dep_id] # Rollback production
+```
+**Deploy sends JSON with base64-encoded files** (not tar.gz). The `POST /api/project/[id]/deploy` endpoint in auto-engineer receives it, uploads to S3, updates Cloudflare KV.
+
+### Database (→ core.blink.new /api/db/[project_id]/sql)
+```bash
+blink db query <sql>                   # Uses linked project
+blink db query <project_id> <sql>      # Explicit project
+blink db exec <file.sql>
+blink db list [table]                  # List tables or rows
+```
+**Arg disambiguation**: two args → arg1=project_id, arg2=sql. One arg → arg1=sql, uses linked project.
+
+### Storage (→ core.blink.new /api/storage/[project_id]/...)
+```bash
+blink storage upload <file>
+blink storage upload <project_id> <file> [--path images/photo.jpg]
+blink storage list [prefix]
+blink storage download <path> [output]
+blink storage delete <path>
+blink storage url <path>
+```
+
+### AI (→ core.blink.new /api/v1/ai/...)
+```bash
+blink ai text <prompt> [--model anthropic/claude-haiku-4.5]
+blink ai image <prompt> [--model fal-ai/nano-banana] [--n 1] [--output file.jpg]
+blink ai image-edit <prompt> <image-url> [--model fal-ai/nano-banana/edit]
+blink ai video <prompt> [--model fal-ai/veo3.1/fast] [--duration 5s] [--aspect 16:9]
+blink ai animate <prompt> <image-url-or-local-file> [--model ...] [--duration 5s]
+blink ai speech <text> [--voice alloy] [--output speech.mp3]
+blink ai transcribe <file-or-url> [--language en]
+```
+
+### Web & Data (→ core.blink.new /api/v1/...)
+```bash
+blink fetch <url> [--method GET] [--body '{"k":"v"}'] [--header "X-Foo: bar"]
+blink search <query> [--count 5]
+```
+
+### Realtime (→ core.blink.new /api/realtime/[project_id]/publish)
+```bash
+blink realtime publish <channel> <data>              # Linked project
+blink realtime publish <project_id> <channel> <data>
+```
+
+### RAG (→ core.blink.new /api/rag/[project_id]/...)
+```bash
+blink rag search <query> [--ai] [--limit 5]
+blink rag search <project_id> <query>
+blink rag upload <file> [--collection <id>]
+blink rag collections [project_id]
+```
+
+### Notifications (→ core.blink.new /api/notifications/[project_id]/email)
+```bash
+blink notify email <to> <subject> [body]
+blink notify email <project_id> <to> <subject> [body]
+blink notify email <to> <subject> --file ./body.html
+```
+
+### Connectors (→ core.blink.new /api/v1/connectors/[provider]/execute)
+```bash
+blink connector exec <provider> <action> [params-json] [--account <id>] [--method POST]
+# e.g.: blink connector exec notion search_pages '{"query":"notes"}'
+```
+
+### Session Context
+```bash
+blink use <project_id>              # Prints export command
+eval $(blink use <project_id> --export)   # Sets BLINK_ACTIVE_PROJECT in shell
+```
+
+### Global Flags (all commands)
+```
+--token <key>     Override BLINK_API_KEY for this command
+--json            Machine-readable JSON output (disables spinners/colors)
+--yes             Skip confirmation prompts
+--profile <name>  Use named config profile (see ~/.config/blink/config.toml)
+--debug           Verbose request logging
+```
+
+---
+
+## Auth Resolution (priority: high → low)
+
+1. `--token <key>` flag
+2. `BLINK_API_KEY` environment variable ← **always set in Claw Fly machines**
+3. `~/.config/blink/config.toml` `[default]` or named `[profile]`
+
+**In Fly machines**: `BLINK_API_KEY`, `BLINK_AGENT_ID`, `BLINK_APIS_URL`, `BLINK_APP_URL` are injected at machine creation — zero config needed.
+
+**Multi-account** (for developers with multiple workspaces):
+```toml
+# ~/.config/blink/config.toml
+[default]
+api_key = "blnk_ak_..."
+workspace_id = "wsp_xxx"
+
+[work]
+api_key = "blnk_ak_..."
+workspace_id = "wsp_yyy"
+```
+Switch: `blink --profile work deploy`
+
+**Project context** (priority: high → low):
+1. `<project_id>` positional argument
+2. `BLINK_ACTIVE_PROJECT` environment variable (`blink use` sets this)
+3. `.blink/project.json` in current directory
+
+---
+
+## How It's Used in Blink Claw Agents
+
+Each Claw agent is a Fly.io Firecracker VM running the OpenClaw Docker image. The CLI is pre-installed at `/usr/local/bin/blink` in that image. Skills use it instead of raw curl:
+
+```bash
+# Before (fragile curl):
+curl -H "Authorization: Bearer ${BLINK_API_KEY}" -H "x-blink-agent-id: ${BLINK_AGENT_ID}" \
+  "${BLINK_APIS_URL}/api/v1/ai/image" -d '{"prompt":"..."}'
+
+# After (CLI one-liner):
+blink ai image "$PROMPT" --json
+```
+
+Skill scripts live in `openclaw/skills/blink-*/scripts/`. After any CLI command change, update the relevant skill scripts.
+
+**Machine env vars injected at agent creation** (`src/app/api/claw/agents/route.ts`):
+```
+BLINK_API_KEY    → auth for all CLI commands
+BLINK_AGENT_ID   → sent as x-blink-agent-id on resource calls (billing)
+BLINK_APIS_URL   → https://core.blink.new
+BLINK_APP_URL    → https://blink.new
+```
+
+---
+
+## Development
+
+```bash
+cd blink-sdk/packages/cli
+npm install
+npm run build           # tsup → dist/cli.js
+node dist/cli.js --help # test
+```
+
+**Adding a new command:**
+1. Create `src/commands/my-command.ts` — export `registerMyCommands(program: Command)`
+2. Determine correct backend: resource API → import from `api-resources.ts`, management → from `api-app.ts`
+3. Register in `src/cli.ts`: `import { registerMyCommands } from './commands/my-command.js'` + call it
+4. Rebuild: `npm run build`
+5. Update relevant skill scripts in `openclaw/skills/`
+6. Update this AGENTS.md command reference
+
+**Adding a new argument pattern:**
+Commander.js does NOT support `[optional] <required>` — the optional arg swallows the required one.
+Always use `<arg1> [arg2]` and disambiguate in the action handler:
+```typescript
+.action((arg1, arg2) => {
+  if (arg2 !== undefined) {
+    projectId = requireProjectId(arg1); value = arg2
+  } else {
+    projectId = requireProjectId(); value = arg1
+  }
+})
+```
+
+---
+
+## Publishing
+
+**GitHub Actions**: `.github/workflows/publish-cli.yml` in the `blink-new/blink-sdk` repo.
+
+**Trigger**: push to `main` with a change to `packages/cli/package.json` (version bump).  
+**Auth**: OIDC Trusted Publisher — no NPM_TOKEN stored. Configured on npmjs.com: org `blinkdotnew`, package `cli`, repo `blink-new/blink-sdk`, workflow `publish-cli.yml`, environment `npm`.
+
+**To release a new version:**
+```bash
+cd blink-sdk
+git checkout main && git pull origin main
+# Edit packages/cli/package.json — bump version (e.g. 0.1.0 → 0.1.1)
+npm run build    # verify it builds
+git commit -am "chore(cli): bump version to 0.1.1"
+git push origin main
+# → GitHub Actions publishes @blinkdotnew/cli@0.1.1 to npm (~60s)
+```
+
+**Version convention:**
+- `0.1.x` — patch: bug fixes, minor arg/output improvements
+- `0.x.0` — minor: new commands, new capabilities
+- `x.0.0` — major: breaking changes to command syntax
+
+**Docker image update**: after publishing, update the `RUN npm install -g @blinkdotnew/cli@X.X.X` line in the Blink Claw Dockerfile (in `openclaw/`) and push to main to trigger a Docker rebuild.
+
+---
+
+## npmjs.com Setup (one-time, already done)
+
+OIDC Trusted Publisher must be configured at npmjs.com:
+- Organization: `blinkdotnew`
+- Package: `cli`
+- GitHub repo: `blink-new/blink-sdk`
+- Workflow file: `publish-cli.yml`
+- Environment: `npm`
+
+GitHub repo must have environment `npm` created (Settings → Environments → New environment → `npm`).