@blinkdotnew/cli 0.3.7 → 0.4.0

package/src/commands/init.ts

@@ -0,0 +1,77 @@
+import { Command } from 'commander'
+import { appRequest } from '../lib/api-app.js'
+import { requireToken } from '../lib/auth.js'
+import { writeProjectConfig } from '../lib/project.js'
+import { printJson, printSuccess, printKv, isJsonMode, withSpinner, printError } from '../lib/output.js'
+import { basename } from 'node:path'
+import chalk from 'chalk'
+
+export function registerInitCommands(program: Command) {
+  program.command('init')
+    .description('Initialize a new Blink project and link it to the current directory')
+    .option('--name <name>', 'Project name (defaults to current directory name)')
+    .option('--from <project_id>', 'Create a new project named after an existing one')
+    .addHelpText('after', `
+Creates a new Blink project and writes .blink/project.json in the current directory.
+After init, all commands work without specifying a project_id.
+
+Examples:
+  $ blink init                             Create project named after current dir
+  $ blink init --name "My SaaS App"        Create with custom name
+  $ blink init --from proj_xxx             Clone from existing project
+  $ blink init --json                      Machine-readable output
+
+After init:
+  $ blink deploy ./dist --prod
+  $ blink db query "SELECT * FROM users"
+  $ blink env set DATABASE_URL postgres://...
+`)
+    .action(async (opts) => {
+      requireToken()
+      if (opts.from) {
+        await initFromExisting(opts.from)
+      } else {
+        await initNew(opts.name)
+      }
+    })
+}
+
+async function initNew(nameOpt?: string) {
+  const name = nameOpt ?? basename(process.cwd())
+  const result = await withSpinner(`Creating project "${name}"...`, () =>
+    appRequest('/api/projects/create', { method: 'POST', body: { prompt: name } })
+  )
+  const proj = result?.project ?? result
+  if (!proj?.id) {
+    printError('Failed to create project — no ID returned')
+    process.exit(1)
+  }
+  writeProjectConfig({ projectId: proj.id })
+  if (isJsonMode()) return printJson({ project_id: proj.id, name: proj.name ?? name })
+  printSuccess(`Project created and linked`)
+  printKv('ID', proj.id)
+  printKv('Name', proj.name ?? name)
+  console.log(chalk.dim('\n  Run `blink deploy ./dist --prod` to deploy'))
+}
+
+async function initFromExisting(sourceId: string) {
+  const source = await withSpinner('Loading source project...', () =>
+    appRequest(`/api/projects/${sourceId}`)
+  )
+  const sourceName = source?.project?.name ?? source?.name ?? sourceId
+  const name = `${sourceName} (copy)`
+  const result = await withSpinner(`Creating project "${name}"...`, () =>
+    appRequest('/api/projects/create', { method: 'POST', body: { prompt: name } })
+  )
+  const proj = result?.project ?? result
+  if (!proj?.id) {
+    printError('Failed to create project — no ID returned')
+    process.exit(1)
+  }
+  writeProjectConfig({ projectId: proj.id })
+  if (isJsonMode()) return printJson({ project_id: proj.id, name: proj.name ?? name, from: sourceId })
+  printSuccess(`Project created from ${sourceId} and linked`)
+  printKv('ID', proj.id)
+  printKv('Name', proj.name ?? name)
+  printKv('From', sourceId)
+}

package/src/commands/security.ts

@@ -0,0 +1,136 @@
+import { Command } from 'commander'
+import { appRequest } from '../lib/api-app.js'
+import { requireToken } from '../lib/auth.js'
+import { requireProjectId } from '../lib/project.js'
+import { printJson, isJsonMode, withSpinner, printSuccess, createTable } from '../lib/output.js'
+import chalk from 'chalk'
+
+function printSecurityPolicy(data: { modules?: Record<string, { require_auth?: boolean }> }) {
+  const modules = data.modules ?? data
+  const table = createTable(['Module', 'Require Auth'])
+  for (const [name, cfg] of Object.entries(modules as Record<string, { require_auth?: boolean }>)) {
+    const status = cfg.require_auth ? chalk.green('yes') : chalk.dim('no')
+    table.push([name, status])
+  }
+  console.log(table.toString())
+}
+
+function printCorsOrigins(origins: string[]) {
+  if (!origins.length) {
+    console.log(chalk.dim('(no CORS origins configured — all origins allowed)'))
+    return
+  }
+  for (const o of origins) console.log(`  ${o}`)
+  console.log(chalk.dim(`\n${origins.length} origin${origins.length === 1 ? '' : 's'}`))
+}
+
+export function registerSecurityCommands(program: Command) {
+  registerSecurityGroup(program)
+  registerCorsGroup(program)
+}
+
+function registerSecurityGroup(program: Command) {
+  const security = program.command('security')
+    .description('Security policy — require auth per module (db/ai/storage/realtime/rag)')
+    .addHelpText('after', `
+Control which backend modules require user authentication.
+When require_auth is true, unauthenticated requests are rejected.
+
+Examples:
+  $ blink security get                                Show security policy
+  $ blink security set --module db --require-auth true
+  $ blink security set --module ai --require-auth false
+`)
+
+  security.command('get [project_id]')
+    .description('Show current security policy')
+    .addHelpText('after', `
+Examples:
+  $ blink security get                  Show policy for linked project
+  $ blink security get proj_xxx         Show policy for specific project
+  $ blink security get --json           Machine-readable output
+`)
+    .action(async (projectArg: string | undefined) => {
+      requireToken()
+      const projectId = requireProjectId(projectArg)
+      const result = await withSpinner('Loading security policy...', () =>
+        appRequest(`/api/project/${projectId}/security`)
+      )
+      if (isJsonMode()) return printJson(result)
+      printSecurityPolicy(result?.policy ?? result)
+    })
+
+  security.command('set [project_id]')
+    .description('Update security policy for a module')
+    .requiredOption('--module <name>', 'Module (db/ai/storage/realtime/rag)')
+    .requiredOption('--require-auth <bool>', 'Require auth (true/false)')
+    .addHelpText('after', `
+Examples:
+  $ blink security set --module db --require-auth true
+  $ blink security set --module ai --require-auth false
+  $ blink security set proj_xxx --module storage --require-auth true
+`)
+    .action(async (projectArg: string | undefined, opts) => {
+      requireToken()
+      const projectId = requireProjectId(projectArg)
+      const requireAuth = opts.requireAuth === 'true'
+      const body = { policy: { modules: { [opts.module]: { require_auth: requireAuth } } } }
+      await withSpinner('Updating security policy...', () =>
+        appRequest(`/api/project/${projectId}/security`, { method: 'PUT', body })
+      )
+      if (isJsonMode()) return printJson({ status: 'ok', module: opts.module, require_auth: requireAuth })
+      printSuccess(`${opts.module}: require_auth = ${requireAuth}`)
+    })
+}
+
+function registerCorsGroup(program: Command) {
+  const cors = program.command('cors')
+    .description('CORS origin management — control which origins can access your project APIs')
+    .addHelpText('after', `
+Manage allowed CORS origins for your project.
+When no origins are configured, all origins are allowed.
+
+Examples:
+  $ blink cors get                                                Show allowed origins
+  $ blink cors set --origins https://example.com https://app.example.com
+`)
+
+  cors.command('get [project_id]')
+    .description('Show allowed CORS origins')
+    .addHelpText('after', `
+Examples:
+  $ blink cors get                   Show origins for linked project
+  $ blink cors get proj_xxx          Show origins for specific project
+  $ blink cors get --json            Machine-readable output
+`)
+    .action(async (projectArg: string | undefined) => {
+      requireToken()
+      const projectId = requireProjectId(projectArg)
+      const result = await withSpinner('Loading CORS config...', () =>
+        appRequest(`/api/project/${projectId}/cors`)
+      )
+      if (isJsonMode()) return printJson(result)
+      const origins: string[] = result?.custom_origins ?? result?.origins ?? []
+      printCorsOrigins(origins)
+    })
+
+  cors.command('set [project_id]')
+    .description('Set allowed CORS origins')
+    .requiredOption('--origins <urls...>', 'Allowed origins (space-separated)')
+    .addHelpText('after', `
+Examples:
+  $ blink cors set --origins https://example.com
+  $ blink cors set --origins https://example.com https://app.example.com
+  $ blink cors set proj_xxx --origins https://example.com
+`)
+    .action(async (projectArg: string | undefined, opts) => {
+      requireToken()
+      const projectId = requireProjectId(projectArg)
+      const origins: string[] = opts.origins
+      await withSpinner('Updating CORS origins...', () =>
+        appRequest(`/api/project/${projectId}/cors`, { method: 'PUT', body: { custom_origins: origins } })
+      )
+      if (isJsonMode()) return printJson({ status: 'ok', origins })
+      printSuccess(`CORS origins set: ${origins.join(', ')}`)
+    })
+}

package/src/commands/tokens.ts

@@ -0,0 +1,98 @@
+import { Command } from 'commander'
+import { appRequest } from '../lib/api-app.js'
+import { requireToken } from '../lib/auth.js'
+import { printJson, isJsonMode, withSpinner, createTable, printSuccess } from '../lib/output.js'
+import chalk from 'chalk'
+
+function printTokenTable(tokens: Array<{ id: string; name: string; key_prefix: string; created_at: string; last_used_at: string }>) {
+  const table = createTable(['ID', 'Name', 'Prefix', 'Created', 'Last Used'])
+  for (const t of tokens) {
+    table.push([
+      t.id,
+      t.name ?? '-',
+      t.key_prefix ?? '-',
+      t.created_at ? new Date(t.created_at).toLocaleDateString() : '-',
+      t.last_used_at ? new Date(t.last_used_at).toLocaleDateString() : 'never',
+    ])
+  }
+  console.log(table.toString())
+}
+
+function printNewToken(token: { id: string; key: string; name: string }) {
+  console.log()
+  printSuccess(`Token created: ${token.name}`)
+  console.log()
+  console.log(chalk.bold('  Token: ') + chalk.green(token.key))
+  console.log()
+  console.log(chalk.yellow('  ⚠ Save this token now — it will not be shown again!'))
+  console.log(chalk.dim('  Use as: export BLINK_API_KEY=' + token.key))
+  console.log()
+}
+
+export function registerTokenCommands(program: Command) {
+  const tokens = program.command('tokens')
+    .description('Manage personal access tokens (API keys)')
+    .addHelpText('after', `
+Examples:
+  $ blink tokens list
+  $ blink tokens create --name "CI deploy key"
+  $ blink tokens revoke tok_xxx --yes
+`)
+
+  tokens.command('list')
+    .description('List all personal access tokens')
+    .addHelpText('after', `
+Examples:
+  $ blink tokens list
+  $ blink tokens list --json
+`)
+    .action(async () => {
+      requireToken()
+      const result = await withSpinner('Loading tokens...', () => appRequest('/api/tokens'))
+      const tokensList = result?.tokens ?? result ?? []
+      if (isJsonMode()) return printJson(tokensList)
+      if (!tokensList.length) return console.log(chalk.dim('No tokens found. Create one with `blink tokens create --name "my key"`.'))
+      printTokenTable(tokensList)
+    })
+
+  tokens.command('create')
+    .description('Create a new personal access token')
+    .requiredOption('--name <name>', 'Name for the token (e.g. "CI deploy key")')
+    .addHelpText('after', `
+Examples:
+  $ blink tokens create --name "CI deploy key"
+  $ blink tokens create --name "staging" --json
+`)
+    .action(async (opts) => {
+      requireToken()
+      const result = await withSpinner('Creating token...', () =>
+        appRequest('/api/tokens', { method: 'POST', body: { name: opts.name } })
+      )
+      if (isJsonMode()) return printJson(result)
+      const token = result?.token ?? result
+      printNewToken(token)
+    })
+
+  tokens.command('revoke <token_id>')
+    .description('Revoke (delete) a personal access token')
+    .option('--yes', 'Skip confirmation')
+    .addHelpText('after', `
+Examples:
+  $ blink tokens revoke tok_xxx
+  $ blink tokens revoke tok_xxx --yes
+`)
+    .action(async (tokenId: string, opts) => {
+      requireToken()
+      const skipConfirm = opts.yes || process.argv.includes('--yes') || process.argv.includes('-y')
+      if (!skipConfirm && !isJsonMode() && process.stdout.isTTY) {
+        const { confirm } = await import('@clack/prompts')
+        const ok = await confirm({ message: `Revoke token ${tokenId}? This cannot be undone.` })
+        if (!ok) { console.log('Cancelled.'); return }
+      }
+      await withSpinner('Revoking token...', () =>
+        appRequest(`/api/tokens/${tokenId}`, { method: 'DELETE' })
+      )
+      if (isJsonMode()) return printJson({ status: 'ok', token_id: tokenId })
+      printSuccess(`Revoked token ${tokenId}`)
+    })
+}

package/src/commands/versions.ts

@@ -0,0 +1,95 @@
+import { Command } from 'commander'
+import { appRequest } from '../lib/api-app.js'
+import { requireToken } from '../lib/auth.js'
+import { requireProjectId } from '../lib/project.js'
+import { printJson, isJsonMode, withSpinner, createTable, printSuccess } from '../lib/output.js'
+import chalk from 'chalk'
+
+function printVersionTable(versions: Array<{ id: string; description?: string; message?: string; created_at: string }>) {
+  const table = createTable(['ID', 'Description', 'Created'])
+  for (const v of versions) {
+    table.push([v.id, v.description ?? v.message ?? '-', new Date(v.created_at).toLocaleString()])
+  }
+  console.log(table.toString())
+}
+
+export function registerVersionCommands(program: Command) {
+  const versions = program.command('versions')
+    .description('Manage project version snapshots')
+    .addHelpText('after', `
+Examples:
+  $ blink versions list
+  $ blink versions save --message "before refactor"
+  $ blink versions restore ver_xxx
+`)
+
+  versions.command('list [project_id]')
+    .description('List saved versions for a project')
+    .addHelpText('after', `
+Examples:
+  $ blink versions list
+  $ blink versions list proj_xxx
+  $ blink versions list --json
+`)
+    .action(async (projectIdArg: string | undefined) => {
+      requireToken()
+      const projectId = requireProjectId(projectIdArg)
+      const result = await withSpinner('Loading versions...', () =>
+        appRequest(`/api/versions?projectId=${projectId}`)
+      )
+      const versionsList = result?.versions ?? result ?? []
+      if (isJsonMode()) return printJson(versionsList)
+      if (!versionsList.length) return console.log(chalk.dim('No versions saved yet.'))
+      printVersionTable(versionsList)
+    })
+
+  versions.command('save [project_id]')
+    .description('Save a version snapshot of the current project state')
+    .requiredOption('--message <msg>', 'Version description (required)')
+    .addHelpText('after', `
+Examples:
+  $ blink versions save --message "stable v1"
+  $ blink versions save proj_xxx --message "pre-deploy"
+  $ blink versions save --json
+`)
+    .action(async (projectIdArg: string | undefined, opts) => {
+      requireToken()
+      const projectId = requireProjectId(projectIdArg)
+      const result = await withSpinner('Saving version...', () =>
+        appRequest('/api/save-version', {
+          method: 'POST',
+          body: { projectId, description: opts.message },
+        })
+      )
+      if (isJsonMode()) return printJson(result)
+      const ver = result?.version ?? result
+      printSuccess(`Version saved: ${ver?.id ?? 'ok'}`)
+    })
+
+  versions.command('restore <version_id> [project_id]')
+    .description('Restore a project to a saved version')
+    .option('--yes', 'Skip confirmation')
+    .addHelpText('after', `
+Examples:
+  $ blink versions restore ver_xxx
+  $ blink versions restore ver_xxx proj_xxx --yes
+`)
+    .action(async (versionId: string, projectIdArg: string | undefined, opts) => {
+      requireToken()
+      const projectId = requireProjectId(projectIdArg)
+      const skipConfirm = opts.yes || process.argv.includes('--yes') || process.argv.includes('-y')
+      if (!skipConfirm && !isJsonMode() && process.stdout.isTTY) {
+        const { confirm } = await import('@clack/prompts')
+        const ok = await confirm({ message: `Restore project ${projectId} to version ${versionId}?` })
+        if (!ok) { console.log('Cancelled.'); return }
+      }
+      const result = await withSpinner('Restoring version...', () =>
+        appRequest('/api/versions/restore', {
+          method: 'POST',
+          body: { projectId, identifier: versionId },
+        })
+      )
+      if (isJsonMode()) return printJson(result)
+      printSuccess(`Restored to version ${versionId}`)
+    })
+}

package/src/commands/workspace.ts

@@ -0,0 +1,130 @@
+import { Command } from 'commander'
+import { appRequest } from '../lib/api-app.js'
+import { requireToken } from '../lib/auth.js'
+import { printJson, isJsonMode, withSpinner, createTable, printSuccess, printError } from '../lib/output.js'
+import chalk from 'chalk'
+
+function printWorkspaceTable(workspaces: Array<{ id: string; name: string; slug: string; tier: string; role: string }>) {
+  const table = createTable(['ID', 'Name', 'Slug', 'Tier', 'Role'])
+  for (const w of workspaces) table.push([w.id, w.name, w.slug ?? '-', w.tier ?? '-', w.role ?? '-'])
+  console.log(table.toString())
+}
+
+function printMemberTable(members: Array<{ name: string; email: string; role: string }>) {
+  const table = createTable(['Name', 'Email', 'Role'])
+  for (const m of members) table.push([m.name ?? '-', m.email, m.role ?? '-'])
+  console.log(table.toString())
+}
+
+export function registerWorkspaceCommands(program: Command) {
+  const workspace = program.command('workspace')
+    .description('Manage workspaces, members, and invitations')
+    .addHelpText('after', `
+Examples:
+  $ blink workspace list
+  $ blink workspace create "My Team"
+  $ blink workspace switch wsp_xxx
+  $ blink workspace members wsp_xxx
+  $ blink workspace invite user@example.com wsp_xxx --role admin
+`)
+
+  workspace.command('list')
+    .description('List all workspaces you belong to')
+    .addHelpText('after', `
+Examples:
+  $ blink workspace list
+  $ blink workspace list --json
+`)
+    .action(async () => {
+      requireToken()
+      const result = await withSpinner('Loading workspaces...', () => appRequest('/api/workspaces'))
+      const workspaces = result?.workspaces ?? result ?? []
+      if (isJsonMode()) return printJson(workspaces)
+      if (!workspaces.length) return console.log(chalk.dim('No workspaces found.'))
+      printWorkspaceTable(workspaces)
+    })
+
+  workspace.command('create <name>')
+    .description('Create a new workspace')
+    .addHelpText('after', `
+Examples:
+  $ blink workspace create "My Team"
+  $ blink workspace create "Acme Corp" --json
+`)
+    .action(async (name: string) => {
+      requireToken()
+      const result = await withSpinner(`Creating "${name}"...`, () =>
+        appRequest('/api/workspaces', { method: 'POST', body: { name } })
+      )
+      if (isJsonMode()) return printJson(result)
+      const ws = result?.workspace ?? result
+      printSuccess(`Created workspace: ${ws.name} (${ws.id})`)
+    })
+
+  workspace.command('switch <workspace_id>')
+    .description('Switch your active workspace')
+    .addHelpText('after', `
+Examples:
+  $ blink workspace switch wsp_xxx
+`)
+    .action(async (workspaceId: string) => {
+      requireToken()
+      await withSpinner('Switching workspace...', () =>
+        appRequest('/api/workspaces/switch', { method: 'POST', body: { workspace_id: workspaceId } })
+      )
+      if (isJsonMode()) return printJson({ status: 'ok', workspace_id: workspaceId })
+      printSuccess(`Switched to workspace ${workspaceId}`)
+    })
+
+  workspace.command('members [workspace_id]')
+    .description('List members of a workspace')
+    .option('--workspace <id>', 'Workspace ID')
+    .addHelpText('after', `
+Examples:
+  $ blink workspace members wsp_xxx
+  $ blink workspace members --workspace wsp_xxx
+  $ blink workspace members wsp_xxx --json
+`)
+    .action(async (workspaceIdArg: string | undefined, opts) => {
+      requireToken()
+      const workspaceId = workspaceIdArg ?? opts.workspace
+      if (!workspaceId) {
+        printError('Workspace ID required', 'blink workspace members wsp_xxx')
+        process.exit(1)
+      }
+      const result = await withSpinner('Loading members...', () =>
+        appRequest(`/api/workspaces/${workspaceId}/members`)
+      )
+      const members = result?.members ?? result ?? []
+      if (isJsonMode()) return printJson(members)
+      if (!members.length) return console.log(chalk.dim('No members found.'))
+      printMemberTable(members)
+    })
+
+  workspace.command('invite <email> [workspace_id]')
+    .description('Invite a member to a workspace')
+    .option('--workspace <id>', 'Workspace ID')
+    .option('--role <role>', 'Role: admin, member, viewer', 'member')
+    .addHelpText('after', `
+Examples:
+  $ blink workspace invite user@example.com wsp_xxx
+  $ blink workspace invite user@example.com --workspace wsp_xxx --role admin
+  $ blink workspace invite user@example.com wsp_xxx --role viewer
+`)
+    .action(async (email: string, workspaceIdArg: string | undefined, opts) => {
+      requireToken()
+      const workspaceId = workspaceIdArg ?? opts.workspace
+      if (!workspaceId) {
+        printError('Workspace ID required', 'blink workspace invite user@example.com wsp_xxx')
+        process.exit(1)
+      }
+      const result = await withSpinner(`Inviting ${email}...`, () =>
+        appRequest(`/api/workspaces/${workspaceId}/invites`, {
+          method: 'POST',
+          body: { emails: [email], role: opts.role },
+        })
+      )
+      if (isJsonMode()) return printJson(result)
+      printSuccess(`Invited ${email} as ${opts.role} to ${workspaceId}`)
+    })
+}

package/src/lib/api-app.ts

@@ -30,7 +30,13 @@ export async function appRequest(path: string, opts: RequestOptions = {}) {
   if (!res.ok) {
     const errText = await res.text()
     let errMsg = `HTTP ${res.status}`
-    try { errMsg = JSON.parse(errText).error ?? errMsg } catch { /* use default */ }
+    try {
+      const parsed = JSON.parse(errText)
+      errMsg = parsed.error ?? parsed.message ?? errMsg
+    } catch { /* use default */ }
+    if (res.status === 401) errMsg += ' — check your API key (blink login --interactive)'
+    if (res.status === 403) errMsg += ' — check project permissions or workspace tier'
+    if (res.status === 404) errMsg += ' — resource not found (check project ID)'
     throw new Error(errMsg)
   }
   const ct = res.headers.get('content-type') ?? ''

package/src/lib/api-resources.ts

@@ -43,6 +43,9 @@ export async function resourcesRequest(path: string, opts: RequestOptions = {})
       else if (parsed.message) errMsg = parsed.message
       else if (err) errMsg = JSON.stringify(err)
     } catch { /* use default */ }
+    if (res.status === 401) errMsg += ' — check your API key (blink login --interactive)'
+    if (res.status === 403) errMsg += ' — check project permissions or workspace tier'
+    if (res.status === 404) errMsg += ' — resource not found (check project ID)'
     throw new Error(errMsg)
   }
   const ct = res.headers.get('content-type') ?? ''

package/src/lib/auth.ts

@@ -21,7 +21,12 @@ export function resolveToken(): string | undefined {
 export function requireToken(): string {
   const token = resolveToken()
   if (!token) {
-    console.error('Error: Not authenticated. Run `blink login --interactive` or set BLINK_API_KEY env var.')
+    process.stderr.write(
+      'Error: Not authenticated.\n' +
+      '  Get your API key at: blink.new/settings?tab=api-keys (starts with blnk_ak_)\n' +
+      '  Then: blink login --interactive           Save to ~/.config/blink/config.toml\n' +
+      '    or: export BLINK_API_KEY=blnk_ak_...    Set env var (CI/agents)\n'
+    )
     process.exit(1)
   }
   return token

package/src/lib/config.ts

@@ -44,10 +44,10 @@ export function readConfig(profile = 'default'): BlinkConfig | undefined {
 }
 
 export function writeConfig(data: BlinkConfig, profile = 'default') {
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true })
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 })
   const existing = existsSync(CONFIG_FILE) ? parseToml(readFileSync(CONFIG_FILE, 'utf-8')) : {}
   existing[profile] = { ...existing[profile], ...data }
-  writeFileSync(CONFIG_FILE, serializeToml(existing))
+  writeFileSync(CONFIG_FILE, serializeToml(existing), { mode: 0o600 })
 }
 
 export function clearConfig(profile = 'default') {

package/src/lib/project.ts

@@ -32,7 +32,13 @@ export function resolveProjectId(explicitId?: string): string | undefined {
 export function requireProjectId(explicitId?: string): string {
   const id = resolveProjectId(explicitId)
   if (!id) {
-    console.error('Error: No project linked. Run `blink link <project_id>` or use `blink use <project_id>`.')
+    process.stderr.write(
+      'Error: No project context.\n' +
+      '  1. blink link <project_id>                   Link to current directory\n' +
+      '  2. export BLINK_ACTIVE_PROJECT=proj_xxx       Set env var (CI/agents)\n' +
+      '  3. Pass project_id as argument                e.g. blink db query proj_xxx "SELECT 1"\n' +
+      "  Don't have a project yet? Run: blink init\n"
+    )
     process.exit(1)
   }
   return id