@vlozi/cli

Connect an MCP client (Claude Code, Claude Desktop, Cursor, ...) to Vlozi with a browser login — no copying a raw API key into a config file by hand. The same CLI also lets you discover and invoke the platform's MCP tools directly from a terminal.

Usage

npx @vlozi/cli auth login

This opens your browser to approve the connection, then automatically configures whatever MCP client it finds on your machine.

npx @vlozi/cli auth status   # check the connection + which tools this key can call
npx @vlozi/cli auth token    # print the raw key, e.g. for piping into a script
npx @vlozi/cli auth logout   # revoke the key and remove it from this machine

Global flags, available on any command: --json (machine-readable output) and --no-color (disable colored output).

Invoking platform tools

Every MCP tool the platform exposes (namespaced as <service>.<tool>, sourced from @repo/service-catalog) is callable and discoverable:

npx @vlozi/cli call blog.list_posts --arg limit=5 --json      # invoke a tool
npx @vlozi/cli call blog.create_draft --arg title="Hello"      # args are key=value
npx @vlozi/cli call collections.create_entry --arg-json data='{"fields":{}}'  # nested JSON args
npx @vlozi/cli tools list                                      # offline catalogue
npx @vlozi/cli tools list --namespace blog                     # filter by service
npx @vlozi/cli tools list --live                               # live server list
npx @vlozi/cli tools get blog.create_draft                     # description + permission
npx @vlozi/cli tools schema blog.list_posts                    # JSON input schema
npx @vlozi/cli tools search subscriber                         # search names + descriptions
npx @vlozi/cli config                                          # endpoints + credential state
npx @vlozi/cli upgrade                                         # check for a newer version
npx @vlozi/cli upgrade --self                                  # check AND install it (npm i -g @vlozi/cli)
npx @vlozi/cli configure                                       # (re-)configure MCP clients on this machine

• Offline by default: the catalogue is bundled, so tools list, get, schema, and call's name/args/permission validation need no network. --live fetches the authoritative list from the gateway instead. (The bundled catalogue is a snapshot of the CLI's own release — --live always reflects what the server currently serves.)
• call validates the tool name, coerces key=value args by the tool's JSON schema (booleans/numbers/arrays), enforces required fields, and (unless --force) pre-checks the stored key's permissions exactly as the server does (a system:owner key bypasses, otherwise the permission must be held literally). For nested objects/arrays, pass --arg-json key='{...}'.
• auth status shows how many of the platform's tools this key can call and the per-service breakdown.
• In human mode, call prints a concise summary of the result (arrays → count + first few items, objects → key list); add --raw to see the full JSON instead.

Exit codes

| Code | Meaning | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | Success. | | 1 | User/request error: not connected, unknown tool, missing/invalid args, permission denied, request rejected by the server (4xx), login denied/expired/consumed/timed out, dead connection on auth status. | | 2 | Server/infra fault (HTTP 5xx or internal_error) from a call. |

--json keeps stdout purely machine-readable; every error goes to stderr as a JSON object with at least an error field.

Health check

npx @vlozi/cli doctor        # human-readable health report
npx @vlozi/cli doctor --json # machine-readable report

doctor runs a read-only, fast check of the whole local setup and exits 1 if any check fails:

• credentials + expiry (warns within 10 days of the 90-day lifetime)
• capability — how many platform tools this key can call
• permissions — that ~/.vlozi/credentials.json is owner-only (POSIX)
• client configs — Claude Code (claude mcp list), Claude Desktop, and Cursor each have a vlozi server whose URL matches the current MCP endpoint
• mcp endpoint and tools shim reachability (the exact vlozi call path)
• registry — a non-fatal check for a newer published version (skips offline)

It never mints, revokes, or logs in, and never prints the API key.

Shell completions

vlozi completion bash > /etc/bash_completion.d/vlozi   # bash
vlozi completion zsh  >> ~/.zshrc                       # zsh
vlozi completion fish > ~/.config/fish/completions/vlozi.fish  # fish

Completions know the command tree and offer fully-qualified <service>.<tool> names (from the offline catalogue) for call and tools get|schema. Re-run the generator after a CLI update to refresh the tool list.

What this does

login mints an ordinary Vlozi API key (the same kind you'd create by hand in Settings → API Keys) via a browser approval step, scoped to whatever role you pick there. Nothing about how MCP itself authenticates changes — this is just a friendlier way to get a key onto your machine instead of copy-pasting one.

Security: the API key is stored in plaintext at ~/.vlozi/credentials.json (chmod 600, owner-only, on macOS/Linux; Windows has no equivalent permission bit). Treat that file like a password — it is the credential. vlozi auth logout revokes it server-side and deletes the file.

Supported clients are auto-detected and configured directly (claude mcp add, or a config-file merge for Claude Desktop / Cursor). Anything else gets a ready-to-paste config block — see the MCP clients docs for the full list.

How call talks to the platform

The CLI talks to the mcp-gateway's REST tool shim:

• GET https://mcp.vlozi.app/tools — list tools for a key (--live)
• POST https://mcp.vlozi.app/tools/<service>.<tool> — invoke a tool

...with Authorization: Bearer <stored key>. This is the same code path native MCP clients drive via POST /mcp (tools/call), just with a simpler envelope. Set VLOZI_TOOLS_URL (or VLOZI_MCP_URL) to point at a staging/dev gateway.

Dashboard commands

vlozi dashboard wraps the workspace-management routes, authenticated with the stored secret API key (the gateway now accepts an ls_... key on these routes — see apps/gateway/src/middleware/api-key-manager.middleware.ts). The manager's permission guards authorize each call by the key's permissions; if your key lacks a permission you get a 403.

npx @vlozi/cli dashboard keys list                          # list API keys
npx @vlozi/cli dashboard keys create -n "ci-key" -e 90d      # create a new API key
npx @vlozi/cli dashboard keys delete <id>                    # revoke a key
npx @vlozi/cli dashboard keys delete <id> --force            # ...even the key currently authenticating this CLI
npx @vlozi/cli dashboard team members                        # list team members
npx @vlozi/cli dashboard team roles                          # list team roles
npx @vlozi/cli dashboard team invite -e [email protected] -r <roleId>  # invite a new team member
npx @vlozi/cli dashboard team remove <id>                    # remove a team member
npx @vlozi/cli dashboard team update-role <id> -r <roleId>   # change a member's role
npx @vlozi/cli dashboard me                                  # your CLI key's own info
npx @vlozi/cli dashboard billing summary                     # plan + credits balance
npx @vlozi/cli dashboard billing plans                       # list available plans
npx @vlozi/cli dashboard billing subscribe -p pro             # change subscription plan
npx @vlozi/cli dashboard workspace info                       # workspace/tenant info
npx @vlozi/cli dashboard                                      # list the subcommands

Reads, writes, and self-service management are all wired: creating/deleting keys, inviting/removing/re-roling team members, and changing plans all go through the same manager routes the dashboard UI uses, gated by the stored key's own permissions (a 403 means your key lacks the permission, not that the command doesn't exist). keys delete refuses to delete the key currently authenticating the CLI unless you pass --force. Publishable (pk_) keys are refused by the gateway — use a secret key.