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 — streaming progress until your service is live at 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
# Homebrewbrew tap koo-io/koobrew install koo
bash
# npmnpm i -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.

bash
koo up

By default koo up waits: it streams the build, then follows the rollout until your service is running and reachable at its URL. 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, and environment to deploy into and records your choice 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 service in the linked environment. koo logs tails its logs; add -f to follow.

bash
koo statuskoo logs -f

Manage variables

Read and change a service's environment 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 injected — handy for a one-off task like a database migration:

bash
koo run -- npm run migrate

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, and environment (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.