@koast.ai/cli

@koast.ai/cli

The Koast command line. Every command is generated from the tool manifest Koast publishes over MCP, so the operations available here are exactly the operations the same credential can perform through an MCP client — no more, no less.

Install

npm install -g @koast.ai/cli

⚠️ Not published yet. @koast.ai/cli is not on npm today — that command returns 404 Not Found - GET https://registry.npmjs.org/@koast%2fcli. Until it is published there is no self-serve download: ask your Koast contact or Koast support for a koast-cli-<version>.tgz build and install that instead:

npm install -g ./koast-cli-0.1.0.tgz

Node 18.17 or newer is required. koast --version prints the installed version.

Sign in

koast login

koast login registers the CLI with Koast's authorization server, opens your browser for approval, and stores the resulting credential in ~/.config/koast/credentials.json with 0600 permissions. No token is ever printed. It blocks while it waits: it runs a one-shot listener on a random 127.0.0.1 port, which is the redirect_uri it registers, and returns once you approve.

koast login --no-browser

prints the authorization URL instead of opening it, then waits the same way. Note that this is not headless login: the redirect_uri is loopback on the machine running the CLI, so a browser on another machine cannot complete it. Forward the port first — ssh -L <port>:127.0.0.1:<port> you@server, using the port the CLI printed.

Where no browser can reach the CLI's machine at all — CI, a locked-down container — set an API key instead:

export KOAST_API_KEY=koast_sk_...

KOAST_API_KEY takes precedence over a stored browser login whenever it is set.

koast logout

removes the stored credential and revokes it with Koast.

Use

koast tools                          # every command this credential can run
koast tools --json                   # the same list with each command's full schema
koast help get-metrics               # one command's arguments, with types and defaults
koast list-brands
koast select-brand --brand-id 12
koast get-metrics --campaign-launch-id abc --level campaign
koast get-metrics --campaign-launch-id abc --level campaign --json

--json prints the tool's full structured result, validated against the tool's published output schema. Without it the CLI prints the tool's rendered summary.

Every command operates on one active brand. If your account has a single brand it is active already; otherwise run koast list-brands and koast select-brand --brand-id <id> first. The choice is remembered in KOAST_CONFIG_DIR, and changing it can change which commands you have, because a brand's ad provider decides which tools apply.

A command that publishes to an ad provider asks for confirmation in the terminal, stating what will be published and the budget. Pass --yes to skip the prompt in a script. With no terminal attached and no --yes, the command refuses with exit code 4.

--yes and --confirm are different things, and confusing them is the one mistake here that costs money. --yes is a CLI flag that skips the terminal prompt. --confirm true is launch-campaign's own argument, and it is what turns a preview into a real publish:

koast launch-campaign --campaign-launch-id abc                 # previews; publishes nothing
koast launch-campaign --campaign-launch-id abc --confirm true  # publishes, after prompting you
koast launch-campaign --campaign-launch-id abc --confirm true --yes   # publishes, no prompt

Tool arguments are camelCase in the API and --kebab-case here: campaignLaunchId is --campaign-launch-id. Run koast help <command> for a command's exact arguments — its prose description is written for an AI client, but the Arguments list is accurate.

Environment

Variable	What
KOAST_API_KEY	An API key to use instead of a browser login
KOAST_MCP_URL	The Koast MCP endpoint. Defaults to https://mcp.koast.ai/mcp
KOAST_CONFIG_DIR	Where the credential, manifest cache and state live. Defaults to ~/.config/koast

Exit codes

Code	Meaning
0	Success
1	The command ran and failed; Koast's own message is on stderr
2	Usage or argument validation error, including a command name this credential does not have
3	Not authenticated: no credential, or one that is wrong, revoked or expired
4	A confirmation was declined or could not be asked for