---
url: 'https://docs.kitbase.dev/cli.md'
description: >-
  The Kitbase CLI — manage webhooks, projects, and analytics from your terminal
  or CI. Browser-based login, API-key auth, and JSON output for scripting.
---

# CLI

The Kitbase CLI (`@kitbase/cli`) lets you do anything the [dashboard](https://app.kitbase.dev) can do, from your terminal — webhooks, projects, analytics, billing, and more, with `--json` output for scripting and CI.

## Installation

::: code-group

```bash [pnpm]
pnpm add -g @kitbase/cli
```

```bash [npm]
npm install -g @kitbase/cli
```

```bash [npx]
npx @kitbase/cli login
```

:::

## Quick start

```bash
# Log in via your browser (no password typed in the terminal)
kitbase login

# Pick a default organization and project so you don't have to pass --org/--project every time
kitbase use org
kitbase use project

# Now run any command
kitbase events list
kitbase webhooks list --json | jq
```

## Authentication

### Browser login (interactive use)

`kitbase login` works like the GitHub CLI: it prints a short code and opens `https://app.kitbase.dev/cli/authorize?session=...` in your browser. Confirm the code on the page matches the one in your terminal, approve, and the CLI picks up the session automatically — instantly via a local loopback ping, or within a few seconds via polling, so it also works over SSH and on headless machines.

::: warning Never approve a login you didn't start yourself.
:::

Credentials are stored in `~/.config/kitbase/credentials.json` (mode `0600`), one entry per API base URL. The access token refreshes automatically in the background; the underlying session lasts 60 days. Run `kitbase logout` to revoke it server-side and clear the local credential.

**A CLI session is exactly as strong as the browser session that approved it.** If your organization requires two-factor authentication, approve the login from a browser session that actually used a second factor — a password-only session produces a CLI token that the organization will refuse. Signing in to the dashboard with your second factor (or with a passkey) before approving is enough.

::: tip Refreshing happens automatically — don't do it yourself.
A refresh token is single-use. If two processes present the same one, Kitbase treats it as a stolen credential and revokes every session for your account, which logs out your other machines too. Running the CLI concurrently is fine; sharing one `credentials.json` between machines is not.
:::

### Private API key (CI/CD)

Create a secret key in the dashboard (**Project Settings → API Keys**, `sk_kitbase_...`), then either export it or pass it per command:

```bash
export KITBASE_API_KEY=sk_kitbase_...
kitbase webhooks list

# or
kitbase webhooks list --api-key sk_kitbase_...
```

A key resolves its own organization and project automatically — no need to run `use org` / `use project` first.

## Organization & project context

Most commands operate on a project inside an organization. Resolution order, per command:

1. `--org` / `--project` flags
2. `KITBASE_ORG` / `KITBASE_PROJECT` environment variables
3. The default set via `kitbase use org` / `kitbase use project`
4. (API-key auth only) resolved automatically from the key itself
5. An interactive picker, if you're in a terminal
6. Otherwise, a clear error telling you what to run

Run `kitbase context` at any time to see the current base URL, auth mode, org, and project.

## Output

Every command prints a human-readable table or key/value view by default. Pass `--json` for machine-readable output:

```bash
kitbase webhooks list --json | jq '.data[].url'
```

## Request bodies

Simple fields are individual flags (`--name`, `--enabled`, ...). For anything with nested objects or arrays, use `--data` — it accepts a literal JSON string, `@file.json`, or `-` for stdin:

```bash
kitbase webhooks create --data '{"name": "Deploy hook", "url": "https://example.com/hooks/kitbase", "events": ["project_created"]}'
echo '{"name": "Deploy hook", ...}' | kitbase webhooks create --data -
kitbase webhooks create --data @webhook.json
```

Individual flags always take precedence over matching keys in `--data`.

## Self-hosted backends

```bash
kitbase webhooks list --local          # shorthand for --base-url http://localhost:8100/api
kitbase webhooks list --base-url https://api.your-domain.com
```

## Commands

`kitbase --help` lists every topic. The session and context commands:

| Command | Description |
| --- | --- |
| `login` | Log in via your browser |
| `logout` | Log out and revoke the session server-side |
| `whoami` | Show the currently logged-in user (or API key context) |
| `use org [slug]` | Set the default organization (interactive picker if omitted) |
| `use project [id]` | Set the default project (interactive picker if omitted) |
| `context` | Show the current base URL, auth mode, org, and project |

Everything else — `webhooks`, `projects`, `ai-visibility`, `backlinks`, `billing`, `events`, `funnels`, `integrations`, `sdk-keys`, `private-api-keys`, `organizations`, `members`, `invitations`, `notifications`, `sessions`, `web-analytics`, and more — is generated from a curated, CLI-scoped subset of the Kitbase API's OpenAPI spec, one command per operation, grouped into topics matching the [API's resource structure](/api-reference). Run `kitbase <topic> --help` to see what's available under it.

## Next steps

* [API reference](/api-reference) — the REST API behind every CLI command.
* [MCP Server](/sdks/mcp) — query the same data from AI assistants instead of the terminal.
* [SDKs & Tools](/sdks/) — all official SDKs and integrations.