CLI reference

uivoid login

npx uivoid login

Opens the uivoid portal in your browser and returns a revocable personal access token to a local loopback callback. Credentials are stored at ~/.config/uivoid/config.json (mode 0600).

For non-interactive environments, skip the browser entirely:

npx uivoid login --token <token>
# or
UIVOID_TOKEN=<token> npx uivoid create my-app --yes

uivoid whoami

npx uivoid whoami
npx uivoid whoami --json

Prints the organization and account you're currently signed in as (pass --json for {"email": "...", "organization": {...}}). uivoid createalso prints this as its first line — if you ever end up creating a project under the wrong account, this is the earliest place you'll see it.

Teams and organizations

npx uivoid org list [--json]
npx uivoid org use <slug>
npx uivoid team list [--org SLUG] [--json]
npx uivoid team invite <email> [--role member|admin|owner] [--org SLUG] [--json]
npx uivoid team revoke <email-or-invite-id> [--org SLUG]
npx uivoid team role <email> <owner|admin|member> [--org SLUG]
npx uivoid team remove <email> [--org SLUG] [--yes]
npx uivoid team leave [--org SLUG] [--yes]
npx uivoid invite accept <link> [--use] [--json]

Commands that act on an organization take --org <slug>; without it they use the default set by uivoid org use (or your only organization). team invite prints a one-time link to share yourself. See Teams & roles.

uivoid create — creating your first project

npx uivoid create [name] [--base-url URL] [--openapi URL]
npx uivoid create [name] --auth-key <value>
npx uivoid create [name] --auth-header "x-api-key:<value>"
npx uivoid create [name] --yes
npx uivoid create [name] --include tool_one,tool_two
npx uivoid create [name] --exclude-destructive
npx uivoid create [name] --no-discover
npx uivoid create [name] --json
npx uivoid create [name] --org <slug>

This is the main command — it turns an existing API into a live MCP server:

1. Prints who you're signed in as, then asks for (or takes via --base-url) your API's base URL. --org <slug> sets which organization to create the project in (defaults to uivoid org use).
2. Discovers its OpenAPI document at /openapi.json, /api/openapi.json, or /swagger.json — use --openapi <url> if it lives elsewhere, or --no-discover to skip discovery and define tools manually afterward.
3. If your API already expects a specific static credential, pass it with --auth-key <value> (sent as Authorization: Bearer <value>) or --auth-header "Header-Name:value" for a different header. Skip both and uivoid generates its own key, printed once after creation — see Authentication.
4. Maps every operation to a tool. GET → read, POST/PUT/PATCH → write, DELETE → destructive.
5. Picks which tools to expose. Interactively, destructive tools start unchecked in the review step. Non-interactively (no TTY), the CLI tells you to pass one of --yes (everything, confirm with a human first), --include <tool1>,<tool2>,..., or --exclude-destructive(the interactive checkbox's own default).
6. Creates the project, activates its MCP server, and prints the MCP URL — or, with --json, a single {mcpUrl, toolCount, scopes: {read, write, destructive}, ...} object.

✓ Created my-app
✓ Found OpenAPI document at https://api.example.com/openapi.json
✓ Mapped 9 scoped tools
✓ MCP server active

Ready  https://my-app.uivoid.app/mcp
Auth: organization login · 9 tools mapped

uivoid credentials

npx uivoid credentials <project> --auth-key <value>
npx uivoid credentials <project> --auth-header "x-api-key:<value>"

Sets or replaces the outbound credential for an existing project without recreating it — useful if you skipped it at create time, the target API rotated its key, or a coding agent guessed wrong the first time. Existing tools keep working immediately; nothing needs to be re-mapped.

uivoid prompt

npx uivoid prompt

Prints a provider-neutral prompt you can hand to any coding agent so it runs the whole integration for you. Same prompt as the "copy a prompt for your LLM to do it" button on uivoid.app and on Setup.

uivoid skill

npx uivoid skill --install

Installs the optional SKILL.md the npm package ships, for coding-agent clients that support agent skills.

uivoid logout

npx uivoid logout

Clears the locally stored credentials.

Troubleshooting: a tool call returns 401

This almost always means the outbound credential, not your uivoid login. The MCP session (you ↔ uivoid) and the outbound call (uivoid ↔ your real API) are authenticated separately — a 401 from a tool call means your API rejected the request uivoid sent it. Check, in order:

1. Did create run with --auth-key/--auth-header, or did it generate its own key? If generated, is that exact value configured on your API? It's only shown once, right after creation — if you lost it, uivoid credentials <project> --auth-key <new-value> sets a fresh one.
2. Is the header name right? Default is Authorization: Bearer <value>; a different expected header (e.g. x-api-key) needs --auth-header, not --auth-key.
3. Only then check the uivoid side: npx uivoid whoamito confirm you're signed in as the right account/org for this project.

Environment variables