robodev

DocsSign in

Reference

CLI reference

Every robodev command.

Getting startedOffline dev with robodev devConnect a frontendStartersDatabaseDomainsFile-based APIsAuthEmailPDFOrganizationsStorageSecretsPushJobsSocketsLLMAgentsDeployLocal developmentCLI reference

Package name: robodev. Tokens live in ~/.robodev/credentials.json. The current folder is linked via robodev/.robodev.

robodev auth

Opens the Starbase OAuth page, listens on a localhost callback, and stores access + refresh tokens.

robodev logout

Deletes ~/.robodev/credentials.json.

robodev whoami

Prints the signed-in email and user id.

robodev projects

Lists projects you can access as id, name, and API URL. Rename or delete a project from the dashboard if you are an organization admin.

robodev create [path] [--starter <id>] [--empty] [--org <id>]

Resolves a starter, then creates a Starbase project named after the folder, copies that starter, writes robodev/.robodev plus VITE_API_URL and VITE_PUBLIC_API_URL, deploys, and runs npm install at the project root. Space, Auth chat, and Marketplace also write a frontend block and try a local Vite build before deploy; a failed FE build still deploys schema + APIs. Those starters print bun next steps, not npm run dev. Refuses to overwrite an existing package.json, robodev/database.ts, robodev/.robodev, or legacy database.ts / .robodev.

  • --starter <id> or --starter=<id> selects that starter and skips the prompt, even on a TTY.
  • --empty is an alias for --starter empty.
  • Passing --empty together with --starter (any id, including empty) exits 1 with Use either --empty or --starter, not both.
  • On a TTY without --starter or --empty, a numbered list of starters is shown. Accept a 1-based index or an id.
  • Without a TTY and without --starter or --empty, the starter is space so existing scripts keep working.
  • Unknown --starter, empty prompt, unknown number, or unknown id exits 1 with Valid ids: space, auth-chat, marketplace, backend, empty.
  • --org <id> or --org=<id> creates the project in that organization and skips the org prompt, even on a TTY. Allowed together with --starter or --empty.
  • On a TTY without --org, if you are an admin of two or more organizations, a numbered list of admin orgs is shown. Accept a 1-based index or an org id.
  • Without a TTY and without --org, or with exactly one admin org, the organization id is omitted so the API uses your oldest admin organization.
  • Unknown organization prompt, empty answer, or unknown id exits 1 and does not create a project. Developer-only memberships are not listed.
  • Unknown other create flags and a missing value after --starter or --org also exit 1. --empty=… is an unknown flag. --organization is not a flag.

Writes robodev/.robodev, VITE_API_URL, and VITE_PUBLIC_API_URL for an existing project. Preserves an existing frontend block or frontend: false. If frontend is absent and apps/fe/package.json exists, writes the default frontend block. Omit the id to pick from a list.

robodev deploy [--force]

Uploads the allowed project file tree (schema, APIs, jobs, and frontend files). When .robodev frontend is set, runs the local Vite build first and aborts on failure. After a successful apply, waits until the project host is live before printing App and Docs URLs. If the host does not become reachable within 30 seconds, the command fails without printing the success banner. Use --force to apply destructive schema changes without a prompt.

robodev dev [--port <n>] [--db-port <n>] [--database-url <url>] [--force] [--no-watch] [--with-fe]

Runs the project on your machine without a Starbase account or hosted project. Finds the backend (database.ts, robodev/database.ts, or packages/be/database.ts, walking up from the current folder), starts an embedded Postgres persisted under .robodev/dev/pg, compiles and pushes the schema, then serves file routes, Robodev Auth (including Google via the platform broker), jobs (ctx.jobs.enqueue and defineJob cron on reserved robodev_jobs tables), sockets on ws://localhost:{port}/sockets/…, storage (bytes in .robodev/dev/storage, GET /storage/objects/{key} returns 200), /openapi.json, Swagger, and a dashboard at /_robodev on http://localhost:4000. Watches the backend tree and reloads on save; a successful reload closes sockets with 1012 deployed; a compile error keeps the previous build serving. Destructive schema changes are printed and skipped until --force. See Offline dev (/docs/dev).

  • --port <n> — API port (default 4000).
  • --db-port <n> — Postgres port (default 0, meaning pick a free one).
  • --database-url <url> — use an existing Postgres instead of the embedded one.
  • --force — apply destructive schema changes.
  • --no-watch — compile once and serve.
  • --with-fe — also start apps/fe with VITE_API_URL, VITE_PUBLIC_API_URL, and APP_PUBLIC_API_URL set to the local API.
  • ctx.llm, ctx.agent, and ctx.push throw llm_not_configured / llm_not_configured / push_not_configured offline. ctx.jobs, ctx.storage, and ctx.sockets run locally. ctx.pdf.fromHtml hops to Starbase. ctx.email prints to the terminal; ctx.env comes from a root .env file.

Environment

  • STARBASE_URL — control-plane API and the offline PDF hop (default https://robodev.povio.dev). See PDF (/docs/pdf).
  • STARBASE_FE_URL — browser UI for OAuth (defaults to STARBASE_URL).