@uidu/cli

The uidu command-line tool. Built to be driven by humans and AI coding agents (Claude Code): read a workspace, scaffold an app, and — soon — provision content.

Status: read, scaffold, authoring, and login are implemented. login needs a registered OAuth client (below). See plans/ai-connector.md.

Login

uidu login opens your browser and signs in via OAuth 2.0 Authorization Code + PKCE (public client) against the uidu doorkeeper provider (https://me.uidu.org/oauth), then stores the Bearer token as apiKey. A loopback server on http://localhost:4123/callback (override with --port) receives the redirect.

One-time backend prereqs (migration + rails console):

# 1. Enable PKCE on doorkeeper (adds code_challenge columns), then migrate + deploy
bin/rails generate doorkeeper:pkce
bin/rails db:migrate

# 2. Register ONE shared public application for the CLI
app = Doorkeeper::Application.create!(
  name: 'uidu CLI',
  redirect_uri: 'http://localhost:4123/callback',
  confidential: false,   # public client -> PKCE, no secret
  scopes: 'public',
)
puts app.uid             # -> UIDU_CLIENT_ID (bake into the CLI or set via env)

Then:

UIDU_CLIENT_ID=<uid> uidu login --workspace <slug>     # opens browser

Non-interactive (CI / AI agents, no browser) — password grant fallback:

UIDU_CLIENT_ID=<uid> UIDU_PASSWORD=... uidu login --email [email protected] --password-grant

Tokens are short-lived (~2h) and the provider issues no refresh token today — re-run uidu login when it expires (or enable use_refresh_token in doorkeeper).

Install

npm install -g @uidu/cli
# or, per-project
npx @uidu/cli --help

Auth

Config resolves in order: CLI flags → env vars → ~/.uidu/config.json.

| Env | Purpose | |---|---| | UIDU_WORKSPACE | Workspace slug (required) | | UIDU_PUBLIC_TOKEN | Read-only token (safe to expose) | | UIDU_API_KEY | Bearer/doorkeeper token for authoring | | UIDU_ENDPOINT | Override GraphQL endpoint | | UIDU_PROJECT_ID | Default project for CMS reads |

Commands

uidu whoami
uidu pages list --project <id> --json
uidu page get home --project <id> --json
uidu events list --json
uidu form get <id> --json

uidu create my-app -t events        # scaffold (delegates to create-uidu-app)

uidu login --email [email protected]        # OAuth (needs UIDU_CLIENT_ID)

# authoring (needs a Bearer token from login, or UIDU_API_KEY):
uidu workspace create --name "Acme"
uidu page create --name Home --slug home --attributes '{"projectId":"..."}'
uidu space create --name "Team"
uidu task create --name "Do the thing"
uidu note create --attributes '{"body":"..."}'
uidu workspace credentials             # rotate/get api key+secret

The --json flag emits machine-readable output only on stdout — this is what agents should parse.

Why a CLI (not MCP)

The primary consumer is Claude Code, which has a shell. A CLI is lighter, works as a human tool too, and is deterministic to evaluate. See the plan for the full rationale and the two-mode auth model (public-token reads vs Bearer authoring against the same GraphQL endpoint).