Skip to content

feat(cli): add --token flag and fetch projects for agent-friendly setup#1

Open
caffeinum wants to merge 3 commits into
mainfrom
feat/agent-ux-improvements
Open

feat(cli): add --token flag and fetch projects for agent-friendly setup#1
caffeinum wants to merge 3 commits into
mainfrom
feat/agent-ux-improvements

Conversation

@caffeinum
Copy link
Copy Markdown

Summary

Agent-experience (AX) improvements to the PowerSync CLI so AI coding agents can complete zero-to-deployed integrations without hitting the dashboard.

Motivation: our eval data shows only ~23% of AI-agent attempts at PowerSync+Supabase integration successfully deploy. Two specific CLI gaps cause most failures — no way to authenticate inline, and no way to discover project IDs without parsing dashboard URLs.

Changes

  • `--token ` flag on all Cloud commands and `fetch instances`. Precedence: `--token` > `PS_ADMIN_TOKEN` env > stored keychain token. Unblocks agents that can't easily export env vars in their tool-calling loop.
  • `powersync fetch projects [--output=json]` command. Lists all projects visible to the token with id/name/org/instance-count. Eliminates the "copy project-id from dashboard URL" step that's the first blocker in every agent run.
  • Improved missing-auth error — now enumerates all three auth paths (`--token`, `PS_ADMIN_TOKEN`, `powersync login`) and links to `dashboard.powersync.com/dashboard/administration/personal-access-tokens`.
  • Clean stderr in JSON mode — spinner is suppressed entirely (not just `isEnabled: false`) so machine-readable output doesn't leak progress text.

Test plan

  • `pnpm build` clean
  • 127/127 tests pass (8 new, covering token precedence, JSON output, error content)
  • `fetch projects --output=json | jq` returns valid JSON, stderr empty
  • `fetch projects` human mode shows spinner + grouped output
  • `--token` overrides invalid `PS_ADMIN_TOKEN` (precedence correct)
  • `deploy --help` shows inherited `--token` flag
  • Live API test against real project (`barkbook`, 2 instances) — all commands work end-to-end

Commits

  • `68e8795` — implementation (13 files, reusable `--token` flag + `fetch projects`)
  • `777d946` — suppress spinner in JSON mode for clean stderr

caffeinum and others added 3 commits April 14, 2026 19:11
Enables AI coding agents to use the PowerSync CLI end-to-end without
visiting the dashboard:

- Add reusable --token flag on all Cloud commands (inherited via
  CloudInstanceCommand.baseFlags) plus fetch instances. Precedence:
  --token > PS_ADMIN_TOKEN env > keychain/stored token. Implemented
  via a process-wide override store mirroring cli-client-headers.
- Add fetch projects command to list Cloud projects the token can
  access (id, name, org, instance count). Supports --output=json for
  piping into jq. Removes the "extract project-id from dashboard URL"
  step.
- Improve not-authenticated error: lists all three auth methods
  (--token flag, PS_ADMIN_TOKEN env, powersync login) and links to
  the PAT creation page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Enables AI agents and CI scripts to persist a PAT without going
through the interactive browser/password flow. When --token is
passed, all prompts are skipped and the token is stored via the
same AuthenticationService path as interactive login.

Safety: on platforms without secure storage, --token alone errors
out pointing to PS_ADMIN_TOKEN or --force-insecure. This prevents
silently writing plaintext tokens to disk.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant