MCP server
Connect AI clients to the CentraKit product MCP server and the docs MCP server, with OAuth setup, scopes, approvals and the full list of 74 product tools.
OpenAPI
Where the CentraKit OpenAPI 3.2 specification lives, how it is generated from route JSDoc and Zod schemas, and how the TypeScript client, reference pages and drift check are built from it.
MCP server
Connect AI clients to the CentraKit product MCP server and the docs MCP server, with OAuth setup, scopes, approvals and the full list of 74 product tools.
OpenAPI
Where the CentraKit OpenAPI 3.2 specification lives, how it is generated from route JSDoc and Zod schemas, and how the TypeScript client, reference pages and drift check are built from it.
Every centrakit CLI command and global flag, how it signs in and resolves the API base URL, its configuration files and environment variables, and how releases are packaged.
The centrakit CLI calls the CentraKit REST API from a terminal, a script or CI. It signs in with a browser PKCE flow or takes a bearer token, and it can call any OpenAPI operation by its ID. The source lives in apps/cli.
The CLI needs Node.js 24 or later. Each published GitHub release has the packaged CLI tarball attached by the CLI release workflow. Install it globally with npm:
npm install -g ./centrakit-<version>.tgz
centrakit --versionInside the monorepo, build and run it with:
pnpm --filter centrakit build
pnpm --filter centrakit cli -- --helpGlobal flags go before or after the command name.
| Flag | Effect |
|---|---|
--base-url <url> | Use this API base URL. Include /api, for example https://api.localhost/api. |
--json | Print output as indented JSON. Also turns off prompts. |
--token <token> | Use this bearer token instead of the stored session. |
--debug | Print stack traces for errors. Also set by CENTRAKIT_CLI_DEBUG=1. |
--no-color | Disable ANSI colors. Also set by NO_COLOR. Colors are also off when output is not a terminal. |
--non-interactive | Never prompt or open a browser. Also set by CI=true or CENTRAKIT_CLI_NON_INTERACTIVE=1. Pass --no-non-interactive or --non-interactive=false to override the environment. |
-V, --version | Print the CLI version. |
-h, --help | Print help for the CLI or a command, for example centrakit orgs create --help. |
An unknown command fails with a suggestion, for example Unknown command `org`. Did you mean `orgs`?. This also works for subcommands, such as centrakit orgs lst.
When the CLI runs in a terminal, it asks for values you leave out instead of failing:
register and forgot-password ask for the email, and register also asks for the first name, last name and password.<organizationId> show a picker of your organizations.logout and orgs delete ask for confirmation. Pass --yes (or -y) to skip it.login shows a spinner while it waits for the browser.Prompts never appear when standard input or output is not a terminal, when --json is set, or in non-interactive mode. In those cases a missing value fails with a message such as Missing the EMAIL argument., and confirmations are skipped. Pressing Ctrl+C at a prompt prints Cancelled. and exits with status 130.
| Command | What it does |
|---|---|
login | Sign in with the browser and store a local session. |
logout | Delete the stored session. |
register <email> | Create an account. |
forgot-password <email> | Send a password reset email. |
whoami | Show the authenticated user. |
health | Show the API health status. |
api <operationId> | Call any OpenAPI operation directly. |
orgs list | List organizations you can access. |
orgs get <organizationId> | Show one organization. |
orgs create | Create an organization. |
orgs update <organizationId> | Update organization settings. |
orgs delete <organizationId> | Delete an organization. |
orgs switch <organizationId> | Set your preferred active organization. |
orgs branding logo set <organizationId> | Upload the organization logo. |
orgs branding logo remove <organizationId> | Remove the organization logo. |
orgs branding images add <organizationId> | Upload a brand image. |
orgs branding images remove <organizationId> | Remove a brand image. |
users me | Show the authenticated user. Same output as whoami. |
Every <organizationId> must be the organization UUID. The CLI rejects anything else before calling the API. In a terminal you can leave it out and pick the organization from a list.
centrakit loginOpens the Supabase OAuth authorization page in your browser, waits for the redirect on a loopback server, exchanges the code with PKCE, and stores the session. The CLI always prints the authorization URL, so you can open it yourself when the browser does not start. The command fails when:
--non-interactive, CI=true or CENTRAKIT_CLI_NON_INTERACTIVE=1 is set;--token or CENTRAKIT_TOKEN is set;CENTRAKIT_OAUTH_CLIENT_ID or the Supabase URL is missing;See Authentication for the flow.
centrakit logoutAsks for confirmation, then deletes session.json. Pass --yes to skip the question. Tokens already issued stay valid until they expire.
centrakit register
centrakit register ada@example.com --first-name Ada --last-name Lovelace
printf '%s' "$PASSWORD" | centrakit register ada@example.com --first-name Ada --last-name Lovelace --password-stdin
centrakit forgot-password ada@example.com
centrakit forgot-password ada@example.com --redirect-path /reset-passwordregister never takes the password as an argument, so it does not end up in your shell history. In a terminal it asks for the password without echoing it. In scripts, pipe it in with --password-stdin; one trailing newline is removed.
--redirect-path is the app path the recovery link opens. It defaults to /reset-password.
centrakit whoami
centrakit users me --json
centrakit healthcentrakit api <operationId> [--path <json>] [--query <json>] [--body <json>]Calls any operation from the OpenAPI spec by its operation ID and always prints JSON. Each option takes a JSON object:
centrakit api listCustomers \
--path '{"organizationId":"1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f"}' \
--query '{"limit":20,"q":"acme"}'
centrakit api setTaskStatus \
--path '{"organizationId":"1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f","taskId":"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"}' \
--body '{"status":"done","position":0}'Find operation IDs on OpenAPI or in REST API.
centrakit orgs list
centrakit orgs get 1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f --json
centrakit orgs switch 1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f
centrakit orgs delete 1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4forgs delete asks for confirmation unless you pass --yes. orgs switch stores a preferred active organization on your profile, which clients can use as a default. It does not change which organization later CLI commands use, because organization routes always take the organization ID explicitly.
centrakit orgs create \
--name "Green Acre Service" \
--slug green-acre \
--website https://greenacre.example \
--address-city Utrecht \
--address-country NL \
--social "LinkedIn|https://linkedin.com/company/greenacre" \
--primary-color "#1F7A4D"| Option | Required | Value |
|---|---|---|
--name <name> | Yes | Organization name. |
--slug <slug> | Yes | URL slug. |
--website <url> | No | Website URL. |
--address-line1 <value> | No | Address line 1. |
--address-line2 <value> | No | Address line 2. |
--address-city <value> | No | City. |
--address-state <value> | No | State or province. |
--address-postal-code <value> | No | Postal code. |
--address-country <value> | No | Country. |
--social <label|url> | No | A social link as label|url. Repeat the flag for more links. |
--primary-color <hex> | No | Primary brand color. |
--secondary-color <hex> | No | Secondary brand color. |
orgs update <organizationId> takes the same options, and --name and --slug are required there too. The API requires the full settings object, so any option you leave out is cleared, as are the phone, IBAN, VAT and Chamber of Commerce fields, which these flags cannot set. To keep existing values, read them with orgs get, then send the complete object with centrakit api updateOrganization --path '{"organizationId":"..."}' --body '<json>'.
centrakit orgs branding logo set 1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f --file ./logo.png
centrakit orgs branding logo remove 1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f
centrakit orgs branding images add 1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f --file ./hero.webp
centrakit orgs branding images remove 1f0c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f --image-id <brandImageId>--file must be a .png, .jpg, .jpeg or .webp file; the CLI picks the content type from the extension. images remove requires --image-id.
The CLI picks a token in this order:
--token <token>.CENTRAKIT_TOKEN.centrakit login. When its access token has expired, the CLI refreshes it with the refresh token and saves the new session. If the refresh fails, the request is sent without a token.CENTRAKIT_TOKEN=<access-token> centrakit orgs list
centrakit --token <access-token> orgs list --jsonThe CLI resolves the base URL in this order:
--base-url <url>.CENTRAKIT_API_URL.apiUrl from the config files, see Configuration.https://api.localhost/api when NODE_ENV is development, otherwise https://api.centrakit.com/api.Always include /api in the base URL, because the CLI appends paths such as /v1/health.
The config directory is ~/.config/centrakit, or CENTRAKIT_CONFIG_DIR when set. It holds:
| File | Contents |
|---|---|
session.json | Access token, refresh token, expiry and user from centrakit login. Written with file mode 600. |
config.json | Optional defaults. Only apiUrl is supported. |
Settings can also come from rc and config files. The CLI merges them in this order, highest first:
centrakit.config.ts (or .mts, .js, .mjs, .json) in the working directory..centrakitrc in the working directory..centrakitrc in $XDG_CONFIG_HOME, or in your home directory when XDG_CONFIG_HOME is not set.config.json in the config directory.Every source accepts the same keys, and only apiUrl is supported. An unknown key or an invalid URL fails with Invalid CLI config.
{
"apiUrl": "https://api.localhost/api"
}An rc file uses key=value lines:
apiUrl=https://api.localhost/apiWhen the project installs centrakit as a dependency, a TypeScript config file can import defineConfig for type checking:
import { defineConfig } from "centrakit/config";
export default defineConfig({
apiUrl: "https://api.localhost/api",
});| Variable | Purpose |
|---|---|
CENTRAKIT_TOKEN | Bearer token to use instead of the stored session. |
CENTRAKIT_API_URL | API base URL. |
CENTRAKIT_CONFIG_DIR | Config directory. |
CENTRAKIT_OAUTH_CLIENT_ID | OAuth client ID for login. Required for browser login. |
CENTRAKIT_SUPABASE_URL | Supabase project URL for login. Falls back to NEXT_PUBLIC_SUPABASE_URL. |
CENTRAKIT_OAUTH_SCOPES | Requested scopes. Defaults to openid email profile. |
CENTRAKIT_OAUTH_REDIRECT_HOST | Loopback callback host. Defaults to 127.0.0.1. |
CENTRAKIT_OAUTH_REDIRECT_PORT | Loopback callback port. Defaults to 8976. |
CENTRAKIT_CLI_NON_INTERACTIVE | 1 enables non-interactive mode. |
CENTRAKIT_CLI_DEBUG | 1 prints stack traces for errors. |
CI | true enables non-interactive mode. |
NO_COLOR | Any non-empty value disables colors. |
The OAuth client must allow the redirect URI http://<host>:<port>/callback, which is http://127.0.0.1:8976/callback by default.
Commands print plain text for strings and indented JSON for objects. --json always prints JSON. orgs list prints the organization array without the pagination wrapper.
When an API call fails, the CLI prints the problem detail (or title) and the code to stderr, for example The organization could not be found. (ORGANIZATION_NOT_FOUND), and exits with status 1. Help and --version exit with 0, and a cancelled prompt exits with 130. See Errors.
CLI releases go through Changesets. When a GitHub release is published, the Release CLI Assets workflow generates the OpenAPI artifacts, lints, typechecks and builds the CLI, packs it with pnpm pack, checks that the tarball contains dist/cli.js, and uploads the tarball to the release. A maintainer can rerun it manually for an existing release tag. See CI and release.
Last updated on
MCP server
Connect AI clients to the CentraKit product MCP server and the docs MCP server, with OAuth setup, scopes, approvals and the full list of 74 product tools.
OpenAPI
Where the CentraKit OpenAPI 3.2 specification lives, how it is generated from route JSDoc and Zod schemas, and how the TypeScript client, reference pages and drift check are built from it.