@blinkdotnew/cli 0.1.1 → 0.1.3

package/AGENTS.md

@@ -254,38 +254,51 @@ Always use `<arg1> [arg2]` and disambiguate in the action handler:
 
 ## Publishing
 
-**GitHub Actions**: `.github/workflows/publish-cli.yml` in the `blink-new/blink-sdk` repo.
+### Normal release flow (automated — use this every time)
 
-**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`.
+1. Edit `packages/cli/package.json` — bump version
+2. Build locally to verify: `npm run build`
+3. Commit and push to `blink-new/blink-sdk` main:
 
-**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"
+# bump version in packages/cli/package.json
+npm run build
+git commit -am "chore(cli): bump version to X.X.X"
 git push origin main
-# → GitHub Actions publishes @blinkdotnew/cli@0.1.1 to npm (~60s)
+# → GitHub Actions (publish-cli.yml) publishes to npm in ~60s. Done.
 ```
 
-**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
+**Workflow**: `.github/workflows/publish-cli.yml`. Fires on any push to `main` that touches `packages/cli/package.json`.  
+**Auth**: OIDC Trusted Publisher — no `NPM_TOKEN` needed, no login required.
 
-**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.
+### Version convention
 
----
+| Bump | When |
+|---|---|
+| `0.1.x` patch | Bug fixes, output/flag tweaks |
+| `0.x.0` minor | New commands, new capabilities |
+| `x.0.0` major | Breaking command syntax changes |
+
+### After publishing — update the Claw Docker image
+
+The CLI is pre-installed in the Blink Claw Docker image via `npm install -g @blinkdotnew/cli`. After publishing a new version, update the install line in the Claw Dockerfile (`openclaw/Dockerfile`) and push to `openclaw` main to trigger a Docker rebuild.
+
+### First-time publish (already done — for reference only)
 
-## npmjs.com Setup (one-time, already done)
+The very first publish cannot use OIDC (package must exist on npm first). It was done manually:
+```bash
+cd blink-sdk/packages/cli
+npm run build
+npm login            # browser 2FA prompt
+npm publish --access public
+```
+Package `@blinkdotnew/cli` now exists on npm. All future publishes use the automated workflow above.
 
-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`
+### OIDC setup (already configured — do not repeat)
 
-GitHub repo must have environment `npm` created (Settings → Environments → New environment → `npm`).
+Trusted Publisher is live:
+- npmjs.com → package `@blinkdotnew/cli` → Settings → Trusted Publishers
+- Repo: `blink-new/blink-sdk`, workflow: `publish-cli.yml`, environment: `npm`
+- GitHub → `blink-new/blink-sdk` → Settings → Environments → `npm` (exists)

package/README.md

@@ -0,0 +1,361 @@
+# @blinkdotnew/cli
+
+The Blink platform CLI. Deploy apps, query databases, generate AI content, manage storage — all from your terminal or agent scripts.
+
+```bash
+npm install -g @blinkdotnew/cli
+blink --help
+```
+
+---
+
+## Quick Start
+
+```bash
+# Install
+npm install -g @blinkdotnew/cli
+
+# Authenticate (enter your blnk_ak_... API key)
+blink login --interactive
+
+# Link a project
+blink link
+
+# Deploy a built app
+blink deploy ./dist --prod
+
+# Query your database
+blink db query "SELECT count(*) FROM users"
+
+# Generate an image
+blink ai image "a glowing blink logo on dark background"
+```
+
+---
+
+## Authentication
+
+The CLI resolves credentials in this order (highest priority first):
+
+| Source | How |
+|---|---|
+| `--token <key>` flag | One-off override per command |
+| `BLINK_API_KEY` env var | CI/CD and Claw agents (set automatically) |
+| `~/.config/blink/config.toml` | Stored after `blink login` |
+
+```bash
+# Interactive login (saves to ~/.config/blink/config.toml)
+blink login --interactive
+
+# One-off with token flag
+blink deploy --token blnk_ak_xxx ./dist
+
+# CI / GitHub Actions
+BLINK_API_KEY=blnk_ak_xxx blink deploy ./dist --prod
+```
+
+Your API key lives at **blink.new → Settings → API Keys** (`blnk_ak_...`).
+
+### Multiple accounts
+
+```toml
+# ~/.config/blink/config.toml
+[default]
+api_key = "blnk_ak_personal"
+
+[work]
+api_key = "blnk_ak_work"
+```
+
+```bash
+blink --profile work deploy ./dist
+```
+
+---
+
+## Commands
+
+### `blink deploy` — Deploy to Blink hosting
+
+```bash
+blink deploy                          # Deploy CWD, use linked project
+blink deploy ./dist                   # Deploy specific build dir
+blink deploy proj_xxx ./dist          # Explicit project + dir
+blink deploy ./dist --prod            # Production (live domain)
+blink deploy ./dist --preview         # Preview URL (default)
+blink deploy ./dist --name "v2 beta"  # Label this deployment
+
+blink deployments                     # List deployments
+blink rollback                        # Rollback production to previous deploy
+```
+
+The CLI packages your **pre-built** output directory and uploads it. Run your build first:
+
+```bash
+npm run build && blink deploy ./dist --prod
+```
+
+Preview deploys get a URL like `preview-a1b2c3d4.sites.blink.new`.  
+Production deploys go to your custom domain or `{id}.sites.blink.new`.
+
+---
+
+### `blink project` — Project management
+
+```bash
+blink project list                    # List all workspace projects
+blink project create "My App"         # Create a new project
+blink project delete proj_xxx         # Delete a project (confirms first)
+
+blink link                            # Link current dir to a project (interactive picker)
+blink link proj_xxx                   # Link to specific project
+blink unlink                          # Remove .blink/project.json
+blink status                          # Show linked project + auth source
+```
+
+Once linked, commands that need a project ID use `.blink/project.json` automatically.
+
+---
+
+### `blink use` — Set active project for a shell session
+
+```bash
+blink use proj_xxx                           # Prints the export command
+eval $(blink use proj_xxx --export)          # Actually sets it in your shell
+export BLINK_ACTIVE_PROJECT=proj_xxx         # Or set manually
+```
+
+After this, omit `proj_xxx` from any command — it's inferred from the env var.
+
+---
+
+### `blink db` — Database (Turso/SQLite per project)
+
+```bash
+# Query (two forms)
+blink db query "SELECT * FROM users LIMIT 10"
+blink db query proj_xxx "SELECT * FROM users LIMIT 10"
+
+# Execute a SQL file
+blink db exec schema.sql
+blink db exec proj_xxx migrations/001.sql
+
+# List tables
+blink db list
+
+# List rows in a table
+blink db list users
+blink db list proj_xxx users --limit 50
+
+# Machine-readable output
+blink db query "SELECT id, email FROM users" --json
+```
+
+---
+
+### `blink storage` — File storage
+
+```bash
+# Upload
+blink storage upload ./logo.png
+blink storage upload proj_xxx ./logo.png --path images/logo.png
+
+# List
+blink storage list
+blink storage list images/
+
+# Download
+blink storage download images/logo.png ./local-logo.png
+
+# Get public URL
+blink storage url images/logo.png
+
+# Delete
+blink storage delete images/old-logo.png
+```
+
+---
+
+### `blink ai` — AI generation
+
+```bash
+# Text
+blink ai text "Summarize this in 3 bullets: ..."
+blink ai text "Write a product description" --model anthropic/claude-sonnet-4.5
+
+# Image
+blink ai image "a futuristic city at sunset"
+blink ai image "a futuristic city" --model fal-ai/nano-banana-pro --n 4
+blink ai image "a city at sunset" --output ./city.jpg
+
+# Image editing
+blink ai image-edit "make it night time" https://example.com/city.jpg
+
+# Video (text-to-video)
+blink ai video "a drone flyover of a neon city"
+blink ai video "timelapse of clouds" --model fal-ai/veo3.1 --duration 10s --aspect 9:16
+
+# Video (image-to-video) — local file or URL
+blink ai animate "make it come alive" ./photo.jpg
+blink ai animate "pan slowly to the right" https://example.com/photo.jpg
+
+# Speech (text-to-speech)
+blink ai speech "Hello, welcome to Blink."
+blink ai speech "Hello world" --voice nova --output ./greeting.mp3
+# Voices: alloy, echo, fable, onyx, nova, shimmer
+
+# Transcription
+blink ai transcribe ./meeting.mp3
+blink ai transcribe https://example.com/audio.mp3 --language en
+```
+
+---
+
+### `blink fetch` and `blink search` — Web & data
+
+```bash
+# Fetch any URL via Blink proxy (handles CORS, auth headers)
+blink fetch https://api.github.com/users/octocat
+blink fetch https://api.example.com/data --method POST --body '{"key":"val"}'
+blink fetch https://api.example.com --header "X-API-Key: secret"
+
+# Web search
+blink search "latest AI news"
+blink search "React Server Components" --count 10 --json
+```
+
+---
+
+### `blink realtime` — Pub/sub
+
+```bash
+# Publish an event to a channel
+blink realtime publish updates '{"type":"refresh"}'
+blink realtime publish proj_xxx updates '{"type":"refresh","data":{"count":42}}'
+```
+
+---
+
+### `blink rag` — Knowledge base / RAG
+
+```bash
+# Search
+blink rag search "how does billing work"
+blink rag search "billing" --ai            # AI-enhanced search
+blink rag search proj_xxx "billing" --limit 10
+
+# Upload a document
+blink rag upload ./docs/faq.md
+blink rag upload proj_xxx ./docs/faq.md --collection coll_xxx
+
+# List collections
+blink rag collections
+```
+
+---
+
+### `blink notify` — Email
+
+```bash
+blink notify email user@example.com "Welcome!" "Thanks for signing up."
+blink notify email user@example.com "Newsletter" --file ./email.html
+blink notify email proj_xxx user@example.com "Subject" "Body"
+```
+
+---
+
+### `blink connector` — OAuth connectors
+
+```bash
+# Execute a connector action (Notion, Google, Slack, HubSpot, etc.)
+blink connector exec notion search_pages '{"query":"meeting notes"}'
+blink connector exec google_calendar list_events '{}'
+blink connector exec slack post_message '{"channel":"C123","text":"Hello"}' --method POST
+blink connector exec notion create_page '{"title":"New Page"}' --account acct_xxx
+```
+
+---
+
+## Global Flags
+
+Available on every command:
+
+| Flag | Description |
+|---|---|
+| `--token <key>` | Override API key for this command only |
+| `--json` | Output raw JSON (no colors, no spinners — great for scripting) |
+| `--yes` | Skip confirmation prompts |
+| `--profile <name>` | Use a named profile from `config.toml` |
+| `--debug` | Print full request/response details |
+| `--version` | Print CLI version |
+| `--help` | Show help for any command |
+
+---
+
+## Scripting & CI/CD
+
+The `--json` flag makes every command machine-readable:
+
+```bash
+# Get deployment URL from a deploy
+URL=$(blink deploy ./dist --prod --json | jq -r '.url')
+echo "Deployed to: $URL"
+
+# Query database and pipe to jq
+blink db query "SELECT id, email FROM users" --json | jq '.[].email'
+
+# Generate image and get URL
+IMG=$(blink ai image "a logo" --json | jq -r '.url')
+blink storage upload ./banner.png --json | jq -r '.url'
+```
+
+### GitHub Actions example
+
+```yaml
+- name: Deploy to Blink
+  env:
+    BLINK_API_KEY: ${{ secrets.BLINK_API_KEY }}
+  run: |
+    npm install -g @blinkdotnew/cli
+    blink deploy ./dist --prod --json
+```
+
+---
+
+## Config Files
+
+| File | Purpose |
+|---|---|
+| `~/.config/blink/config.toml` | Auth tokens, workspace ID, named profiles |
+| `.blink/project.json` | Per-directory project link (like `.vercel/project.json`) |
+
+`.blink/project.json` is created by `blink link` — add it to `.gitignore`.
+
+---
+
+## Blink Claw Agents
+
+The CLI is **pre-installed** in every Blink Claw agent (Fly.io Firecracker VM). These env vars are already injected — no login needed:
+
+```
+BLINK_API_KEY    auth token
+BLINK_AGENT_ID   per-agent billing identity
+BLINK_APIS_URL   https://core.blink.new
+BLINK_APP_URL    https://blink.new
+```
+
+Agents use the CLI directly in skill scripts:
+
+```bash
+# In openclaw/skills/blink-image/scripts/generate.sh
+blink ai image "$PROMPT" --model "$MODEL" --json
+```
+
+---
+
+## Links
+
+- **npm**: https://www.npmjs.com/package/@blinkdotnew/cli
+- **Blink platform**: https://blink.new
+- **Docs**: https://blink.new/docs
+- **Source**: `blink-sdk/packages/cli/` in the `blink-new/blink-sdk` repo