Koo Docs
View as Markdown

Koo CLI

The Koo CLI deploys your app from your terminal. Its flagship command, koo up, packs your working directory, uploads it, builds it, and rolls it out — following progress until your service is online, then printing its URL.

Install

The CLI is a single self-contained binary for macOS, Linux, and Windows. Install it with your package manager of choice.

bash
# Homebrew (6.0+ requires trusting third-party taps)brew tap koo-io/koobrew trust koo-io/koobrew install koo
bash
# npmnpm install -g @koo-io/cli
bash
# Cargocargo install koo

Run koo --version to confirm the install.

Log in

koo login opens your browser to authorize the CLI, then stores the session in your operating system's keyring — nothing is written to disk in plaintext. koo whoami prints who you're acting as, and koo logout clears the stored session.

bash
koo loginkoo whoami

For CI and other headless environments, skip the browser step: set KOO_TOKEN to a kc_… API token and every command authenticates with it.

Deploy with koo up

From your app's directory, run koo up. It packs the working tree — honoring .gitignore, .kooignore, and .dockerignore — uploads it, builds a container image, and ships it as a new deployment. This section covers the essentials; the koo up guide is the full walkthrough.

bash
koo up

By default koo up waits: it shows the build's progress stage by stage, then follows the rollout until your service reports online, and prints its URL. The full build log isn't streamed to your terminal — when a build fails, the CLI prints the log's tail so you can see why. Pass --detach to return as soon as the deploy is queued.

The first time you run it in a directory, koo up asks which account, project, environment, and service to deploy into — picking or creating each — and records all four in a koo.json file. To set that up ahead of time, run koo link yourself.

bash
koo link

This is the same from-source path as Deploy from Git, driven from your machine instead of a repository. To ship a prebuilt image instead, see Deploy a container.

Watch your service

koo status shows the current health and live URL of the linked service. koo logs tails its logs; add -f to follow.

bash
koo statuskoo logs -f

Manage variables

Read and change a service's variables without leaving the terminal.

bash
koo variables listkoo variables set DEBUG=truekoo variables unset DEBUG

Run a command locally with the service's variables in scope — handy for running your app against its real configuration:

bash
koo run -- npm run dev

Sensitive values — database URLs, passwords — are withheld: the CLI skips them with a notice naming each one. When a command needs one, reveal it in the console.

Command reference

CommandWhat it does
koo login / koo logoutAuthorize the CLI, or clear the stored session.
koo whoamiShow the current actor.
koo linkBind the current directory to an account, project, environment, and service (koo.json).
koo upPack, upload, build, and deploy the working directory.
koo statusShow the linked service's health and live URL.
koo logsTail the service's logs (-f to follow).
koo variablesList, set, or unset environment variables.
koo run -- <cmd>Run a command with the service's variables in scope.
koo accounts / koo projects / koo environmentsList the accounts, projects, and environments you can reach.
  • Quickstart — sign up to a live app in about ten minutes.
  • API tokens — the kc_… tokens the CLI uses for headless auth.