@blinkdotnew/cli 0.3.7 → 0.4.1

package/README.md

@@ -1,427 +1,258 @@
-# @blinkdotnew/cli
+# Blink CLI
 
-The Blink platform CLI. Deploy apps, query databases, generate AI content, manage storage, and control Blink Claw agents — all from your terminal or agent scripts.
+The command-line interface for [Blink](https://blink.new) — full-stack cloud infrastructure from your terminal.
+
+Create projects, deploy frontends, manage databases, configure auth, set up custom domains, and more. Designed for developers and AI coding agents alike.
+
+```bash
+npx @blinkdotnew/cli --help
+```
+
+## Install
 
 ```bash
 npm install -g @blinkdotnew/cli
-blink --help
 ```
 
----
+Requires Node.js 22+.
 
 ## Quick Start
 
 ```bash
-# Install
-npm install -g @blinkdotnew/cli
-
-# Authenticate (enter your blnk_ak_... API key from blink.new → Settings → API Keys)
+# Authenticate
 blink login --interactive
 
-# See full context: agent + project + auth
-blink status
-
-# Manage Claw agents
-blink agent list
-eval $(blink agent use clw_xxx --export)
-blink secrets set GITHUB_TOKEN ghp_xxx
-blink secrets list
+# Create and link a project
+blink init --name "my-app"
 
-# Deploy an app
+# Deploy
 npm run build && blink deploy ./dist --prod
 
-# Query your database
-blink db query "SELECT count(*) FROM users"
-
-# Generate AI content
-blink ai image "a glowing blink logo on dark background"
-blink ai text "Summarize this article: ..."
-
-# Scrape websites
-blink scrape https://lovable.dev --extract "pricing tiers and costs"
-blink scrape https://example.com --text
+# Done — your app is live
 ```
 
----
+## What You Can Do
 
-## Authentication
+| Command | Description |
+|---------|-------------|
+| `blink init` | Create a new project and link it to the current directory |
+| `blink deploy ./dist --prod` | Deploy your built app to production |
+| `blink db query "SELECT * FROM users"` | Run SQL against your project's database |
+| `blink env set STRIPE_KEY sk_live_xxx` | Set environment variables (secrets) |
+| `blink backend deploy` | Deploy a Hono backend to Cloudflare Workers |
+| `blink auth-config set --provider google --enabled true` | Configure authentication providers |
+| `blink domains add myapp.com` | Connect a custom domain |
+| `blink hosting activate` | Activate production hosting |
+| `blink storage upload ./photo.jpg` | Upload files to project storage |
+| `blink ai image "a logo for my app"` | Generate images, text, video, speech |
 
-The CLI resolves credentials in this order (highest priority first):
+## Full Command Reference
 
-| 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` |
+### Project Management
 
 ```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
+blink init                              # Create project + link to current dir
+blink init --name "My App"              # Create with custom name
+blink link                              # Link existing project (interactive picker)
+blink link proj_xxx                     # Link to specific project
+blink project list                      # List all projects
+blink project create "My App"           # Create without linking
+blink project delete proj_xxx --yes     # Delete a project
+blink status                            # Show current context (project + auth)
 ```
 
-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"
-```
+### Deploy
 
 ```bash
-blink --profile work deploy ./dist
+blink deploy ./dist --prod              # Deploy to production
+blink deploy ./dist                     # Preview deployment
+blink deployments                       # List past deployments
+blink rollback                          # Rollback to previous version
 ```
 
----
+### Database
 
-## Commands
-
-### `blink deploy` — Deploy to Blink hosting
+Each project gets its own SQLite database powered by libSQL.
 
 ```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
+blink db query "SELECT * FROM users LIMIT 10"
+blink db exec schema.sql                # Run a SQL file
+blink db list                           # Show all tables
+blink db list users                     # Show rows in a table
 ```
 
-The CLI packages your **pre-built** output directory and uploads it. Run your build first:
+### Environment Variables
 
 ```bash
-npm run build && blink deploy ./dist --prod
+blink env list                          # List all env vars
+blink env set DATABASE_URL postgres://...
+blink env delete OLD_KEY
+blink env push .env                     # Bulk import from .env file
+blink env pull > .env.local             # Export to file
 ```
 
-Preview deploys get a URL like `preview-a1b2c3d4.sites.blink.new`.  
-Production deploys go to your custom domain or `{id}.sites.blink.new`.
-
----
+### Backend (Cloudflare Workers)
 
-### `blink project` — Project management
+Deploy a Hono server to Cloudflare Workers for Platforms — each project gets its own isolated V8 worker.
 
 ```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
+blink backend deploy                    # Deploy backend/ folder
+blink backend deploy ./server           # Deploy from custom directory
+blink backend status                    # Check deployment status
+blink backend logs                      # View request logs
+blink backend delete --yes              # Remove backend
 ```
 
-Once linked, commands that need a project ID use `.blink/project.json` automatically.
-
----
-
-### `blink use` — Set active project for a shell session
+### Auth Configuration
 
 ```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
+blink auth-config get                   # Show current auth config
+blink auth-config set --provider google --enabled true
+blink auth-config set --mode managed
+blink auth-config byoc-set --provider google --client-id X --client-secret Y
+blink auth-config byoc-remove --provider google
 ```
 
-After this, omit `proj_xxx` from any command — it's inferred from the env var.
-
----
-
-### `blink db` — Database (Turso/SQLite per project)
+### Custom Domains
 
 ```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
+blink domains list                      # List project domains
+blink domains add myapp.com             # Add a custom domain
+blink domains verify <domain_id>        # Verify DNS configuration
+blink domains remove <domain_id> --yes  # Remove a domain
+blink domains search "myapp"            # Search available domains
+blink domains purchase myapp.com --yes  # Purchase a domain
+blink domains connect myapp.com         # Connect purchased domain to project
+blink domains my                        # List your purchased domains
+```
 
-# List rows in a table
-blink db list users
-blink db list proj_xxx users --limit 50
+### Hosting
 
-# Machine-readable output
-blink db query "SELECT id, email FROM users" --json
+```bash
+blink hosting status                    # Check hosting state + URLs
+blink hosting activate                  # Activate production hosting
+blink hosting deactivate --yes          # Deactivate hosting
+blink hosting reactivate                # Reactivate after deactivation
 ```
 
----
-
-### `blink storage` — File storage
+### Storage
 
 ```bash
-# Upload
-blink storage upload ./logo.png
-blink storage upload proj_xxx ./logo.png --path images/logo.png
-
-# List
+blink storage upload ./photo.jpg
 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 storage url images/photo.jpg      # Get CDN URL
+blink storage download images/photo.jpg ./local.jpg
+blink storage delete images/old.jpg
 ```
 
----
-
-### `blink ai` — AI generation
+### AI
 
 ```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 text "Summarize this: ..."
 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 video "ocean waves" --duration 10s
+blink ai speech "Hello world" --voice nova --output hello.mp3
 blink ai transcribe ./meeting.mp3
-blink ai transcribe https://example.com/audio.mp3 --language en
 ```
 
----
-
-### `blink fetch`, `blink search`, `blink scrape` — Web & data
+### Security & CORS
 
 ```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
-
-# Scrape web pages
-blink scrape https://example.com                              # Raw response
-blink scrape https://example.com --text                      # Clean text (strips HTML)
-blink scrape https://example.com --extract "all prices"      # AI-extract specific data
-blink scrape https://news.ycombinator.com --extract "top 10 story titles and URLs"
-blink scrape https://example.com --extract "contact email" --json
+blink security get                      # Show per-module auth policy
+blink security set --module db --require-auth true
+blink cors get                          # Show allowed origins
+blink cors set --origins https://example.com https://app.example.com
 ```
 
-No project key needed — `blink scrape` uses your workspace key only.
-
-- `--text` — strips all HTML tags, returns readable text
-- `--extract <instructions>` — uses AI (Gemini Flash) to extract exactly what you ask for
-- Combine with `--json` for `{ url, content }` or `{ url, extracted }` output
-
----
-
-### `blink realtime` — Pub/sub
+### Workspace Management
 
 ```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 workspace list                    # List workspaces
+blink workspace create "My Team"        # Create a workspace
+blink workspace switch wsp_xxx          # Switch active workspace
+blink workspace members wsp_xxx         # List members
+blink workspace invite user@example.com wsp_xxx --role admin
 ```
 
----
-
-### `blink rag` — Knowledge base / RAG
+### Versions
 
 ```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 versions list                     # List saved snapshots
+blink versions save --message "v1.0"    # Save a snapshot
+blink versions restore ver_xxx --yes    # Restore to a snapshot
 ```
 
----
-
-### `blink notify` — Email
+### Billing
 
 ```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 credits                           # Check credit usage
+blink usage                             # Usage breakdown
+blink usage --period month              # Monthly summary
 ```
 
----
-
-### `blink connector` — OAuth connectors
+### Personal Access Tokens
 
 ```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
+blink tokens list                       # List all PATs
+blink tokens create --name "CI key"     # Create a new token (shown once)
+blink tokens revoke tok_xxx --yes       # Revoke a token
 ```
 
----
-
-## 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 |
+## Authentication
 
----
+Three ways to authenticate, checked in this order:
 
-## Scripting & CI/CD
+1. **`--token` flag** — per-command override
+2. **`BLINK_API_KEY` env var** — for CI/CD and coding agents
+3. **Config file** — saved by `blink login --interactive` at `~/.config/blink/config.toml`
 
-The `--json` flag makes every command machine-readable:
+Get your API key at [blink.new/settings?tab=api-keys](https://blink.new/settings?tab=api-keys).
 
 ```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
+# Interactive — saves to config file
+blink login --interactive
 
-The CLI is **pre-installed** in every Blink Claw agent (Fly.io Firecracker VM). These env vars are already injected — no login needed:
+# Environment variable — for CI/agents
+export BLINK_API_KEY=blnk_ak_...
 
-```
-BLINK_API_KEY    auth token (workspace-scoped)
-BLINK_AGENT_ID   this agent's ID — auto-used by blink agent/secrets commands
-BLINK_APIS_URL   https://core.blink.new
-BLINK_APP_URL    https://blink.new
+# Per-command
+blink deploy ./dist --prod --token blnk_ak_...
 ```
 
-Agents use the CLI directly in skill scripts:
+## Project Context
 
-```bash
-# In openclaw/skills/blink-image/scripts/generate.sh
-blink ai image "$PROMPT" --model "$MODEL" --json
-```
-
-### `blink agent` — Manage agents
+Commands that operate on a project resolve it in this order:
 
-```bash
-blink agent list                           # List all agents in workspace
-blink agent use clw_xxx                    # Show how to set active agent
-eval $(blink agent use clw_xxx --export)   # Set active agent for this session
-blink agent status                         # Show current agent details
-blink agent status clw_xxx                 # Show specific agent details
-```
+1. **Positional argument** — `blink db query proj_xxx "SELECT 1"`
+2. **`BLINK_ACTIVE_PROJECT` env var** — `eval $(blink use proj_xxx --export)`
+3. **`.blink/project.json`** — created by `blink link` or `blink init`
 
-On Claw machines, `BLINK_AGENT_ID` is already set — `blink agent status` works with zero config.
+## Machine-Readable Output
 
-### `blink secrets` — Agent encrypted vault
+Every command supports `--json` for scripting and AI agent integration:
 
 ```bash
-# All commands auto-use BLINK_AGENT_ID on Claw machines
-blink secrets list                         # List secret key names (values never shown)
-blink secrets set GITHUB_TOKEN ghp_xxx     # Add or update a secret
-blink secrets delete OLD_KEY               # Remove a secret (--yes to skip prompt)
-
-# Cross-agent management (agent manager pattern)
-blink secrets list --agent clw_other       # Another agent's keys
-blink secrets set --agent clw_other OPENAI_KEY sk-xxx   # Set on another agent
+blink deploy ./dist --prod --json | jq '.url'
+blink db query "SELECT email FROM users" --json | jq '.[].email'
+blink env list --json | jq '.[].key'
 ```
 
-Secrets are stored encrypted and available as `$KEY_NAME` in all agent shell commands.
+## For Coding Agents
 
-Agent ID resolution for `blink agent` and `blink secrets`:
-1. `--agent <id>` flag
-2. `BLINK_AGENT_ID` env var ← always set on Claw Fly machines
-3. `BLINK_ACTIVE_AGENT` env var ← from `eval $(blink agent use clw_xxx --export)`
+The Blink CLI is designed to work seamlessly with AI coding agents like Cursor, Claude Code, and Codex:
 
-### `blink status` — Full context at a glance
+- **Non-interactive by default** — all inputs are flags, no menus or prompts
+- **`--json` mode** — structured output for every command
+- **`--yes` flag** — skip confirmations for automation
+- **Actionable errors** — every error message includes the exact command to fix it
+- **Layered help** — `blink --help` for overview, `blink backend --help` for a group, `blink backend deploy --help` for full details
 
-```bash
-$ BLINK_AGENT_ID=clw_xxx blink status
-
-Agent    clw_xxx           (BLINK_AGENT_ID env)
-Project  proj_yyy          (.blink/project.json)
-Auth     ~/.config/blink/config.toml
-```
+## Links
 
----
+- [Blink](https://blink.new) — Build full-stack apps with AI
+- [Documentation](https://blink.new/docs/cli)
+- [SDK](https://www.npmjs.com/package/@blinkdotnew/sdk)
 
-## Links
+## License
 
-- **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
+MIT