CLI

The kraken command-line interface ships with the Agent SDK. Use it to scaffold projects, generate types, validate a project, run agents locally, authenticate, and manage API keys.

#Installation

The kraken CLI is the binary from @kraken-ai/platform. It is installed automatically as a project dependency, so there is nothing to install globally — every scaffolded project can invoke it through its package manager.

To start a new project, run the scaffolder. It generates a typed multi-agent project with @kraken-ai/platform already wired in, so kraken is available immediately.

$ pnpm create @kraken-ai/agents my-projectnpm create @kraken-ai/agents my-project

Inside a project, invoke the CLI through your package manager (for example pnpm kraken <command>) or through npx kraken <command>. The generated package.json also exposes dev, check, and build scripts that call the CLI for you. See the Quickstart for an end-to-end walkthrough.

Note

Run kraken --help for the full command list, or kraken api-keys with no subcommand for API-key usage.

#create-agents

@kraken-ai/create-agents scaffolds a production-ready Kraken project. Run it with no flags for an interactive setup, or pass flags to skip the prompts entirely.

$ npx @kraken-ai/create-agents [project-name] [options]

# Non-interactive: starter template on an OpenAI model, no Biome
$ npx @kraken-ai/create-agents my-project \
    --template starter --model openai/gpt-5.4 --no-biome

[project-name]positionalOptional

Project directory name. Lowercase letters, numbers, and hyphens only. May also be passed as --name <name>. Prompted for if omitted.

-t, --templatemarket-intel | starterOptional

Project template. Defaults to market-intel.

-m, --modelstringOptional

Model every generated agent runs on: google/gemini-3-flash-preview (default), google/gemini-3.1-pro-preview, or openai/gpt-5.4.

--pmpnpm | npm | yarn | bunOptional

Package manager used to install dependencies. Auto-detected from the invoking tool when omitted.

--biomebooleanOptional

Include Biome for linting and formatting.

--no-biomebooleanOptional

Skip Biome setup.

--localbooleanOptional

Pack local SDK tarballs into .local-deps for the scaffolded install. Used when developing against unpublished SDK builds.

--skip-gitbooleanOptional

Skip git init and the initial commit.

--skip-installbooleanOptional

Skip the post-scaffold dependency install.

--jsonbooleanOptional

Emit a structured JSON result to stdout instead of interactive output.

--dry-runbooleanOptional

Validate inputs and print the files that would be created without writing anything.

-h, --helpbooleanOptional

Print usage and exit.

-v, --versionbooleanOptional

Print the scaffolder version and exit.

For a tour of the two templates and their generated file layouts, see Examples.

#kraken generate

Discovers local agents, connectors, skills, and actions in src/, fetches remote schemas from the connected platform when you are logged in, and writes type definitions the rest of your project consumes. The scaffolded postinstall script runs this automatically after install.

$ kraken generate

# Verify generated types are up to date (CI-friendly; exits 1 if stale)
$ kraken generate --check

--dirpathOptional

Project root and output directory. Defaults to the current working directory.

--checkbooleanOptional

Check whether generated types are current without writing. Exits with code 1 if the types are stale.

Note

Without stored credentials, generation runs from local definitions only. Run kraken login first to also sync schemas for primitives that already exist on the platform.

#kraken dev

Runs an agent locally with an interactive REPL, against your model provider key — no deployed platform required. With no argument, it picks the single agent in src/agents/, or prompts you to choose when there is more than one.

$ kraken dev

# Run a specific agent and print prompts, tools, and tool I/O
$ kraken dev researcher.ts --debug

[agent]positionalOptional

Agent filename, for example researcher.ts. Optional — resolved from src/agents/ when omitted.

--debugbooleanOptional

Print the full system prompt, the registered tools, and per-turn tool arguments and results.

#kraken validate

An offline check of the project manifest: kebab-case filenames, reserved names, a flat primitive layout, connector ambiguity, local duplicate names, and camelCase injectivity. The scaffolded prebuild script runs this before a build.

$ kraken validate

# Machine-readable report
$ kraken validate --json

--dirpathOptional

Project root. Defaults to the current working directory.

--jsonbooleanOptional

Emit a machine-readable report instead of human-readable output.

kraken login authenticates against a platform instance using browser-based device authorization: it prints a device code, opens the verification URL, and stores the resulting credentials locally. kraken logout clears them.

$ kraken login --url https://your-platform-url
$ kraken logout

--urlplatform-urlOptional

Platform instance URL. Prompted for if omitted. Must be an HTTP(S) URL.

Stored credentials are used by kraken generate to fetch remote schemas and by kraken api-keys to manage keys.

#kraken api-keys

Manage API keys used for server-side SDK authentication with the Platform SDK. Requires stored credentials from kraken login.

$ kraken api-keys create --name "my-app" --expires 90d
$ kraken api-keys list --env prod
$ kraken api-keys revoke <id>

createsubcommandOptional

Create a new API key. Requires --name <name>. Accepts --env <dev|staging|prod> (defaults to dev) and --expires <duration> (for example 24h, 90d, 1y). The key is shown once at creation time.

listsubcommandOptional

List all API keys. Accepts an optional --env <dev|staging|prod> filter.

revokesubcommandOptional

Revoke an API key by id: kraken api-keys revoke <id>.

Important

A created key is displayed only once. Copy it immediately and store it in your environment or your hosting provider’s secret store — it cannot be retrieved again.

#Environment variables

The CLI and the SDKs read the following variables. Stored credentials from kraken login are used unless overridden by these.

KRAKEN_BASE_URLstringOptional

Platform instance URL. Overrides the stored credential URL.

KRAKEN_API_KEYstringOptional

API key for server-side SDK authentication. Overrides stored credentials.

KRAKEN_DEBUG1Optional

Propagated by kraken dev --debug into the agent subprocess to print the full system prompt, registered tools, and per-turn tool arguments and results. Pass --debug; setting this variable in your shell alone does not enable debug output.

GOOGLE_API_KEYstringOptional

Model provider key, required when running an agent on a google/* model.

OPENAI_API_KEYstringOptional

Model provider key, required when running an agent on an openai/* model.

The scaffolder writes a .env.example containing the provider key for the model you chose plus the platform variables. Copy it to .env and fill in your values.

Local runs — only the model provider key is required for kraken dev. Leave the platform variables empty.
Platform access — set KRAKEN_BASE_URL and KRAKEN_API_KEY to call a deployed platform from the SDK.

#Next steps

Quickstart — Scaffold a typed project, configure a model key, run an agent locally, and deploy by connecting a repository.
Examples — The starter and market-intelligence templates: what each demonstrates and the exact files they generate.