Tektona CLI

The tektona CLI manages sandboxes, API keys, and your active org and project from the shell. It wraps the same HTTP API as the SDKs and ships with helpers for SSH, VNC, and port forwarding into running sandboxes.

Install

npm install -g @tektona/cli

pnpm add -g @tektona/cli

bun add -g @tektona/cli

brew install tektona-ai/tap/tektona

The npm package installs a small launcher that selects the platform-specific Tektona binary for macOS, Linux, or Windows. The Homebrew formula installs a native binary for macOS and Linux.

Verify:

tektona --version

Get started

Follow these steps once after installing. The whole flow takes a couple of minutes.

tektona login

tektona ctx show

Org:     acme-corp            (config)
Project: backend              (config)
API:     https://api-dev.tektona.ai (config)

tektona ctx set

tektona ctx set acme-corp/backend   # qualified ref
tektona ctx set acme-corp backend   # two arguments

tektona ctx set --global acme-corp/backend   # machine-wide default

tektona ctx set-url https://api-dev.tektona.ai

tektona project ls                  # all your projects, across every org
tektona project ls --org acme-corp  # filter to one org
tektona project ls -o json          # machine-readable

That's it. You're ready to create a sandbox.

Configuring without the wizard

Everything tektona login does can also be set directly.

API endpoint. Persist it with tektona ctx set-url https://api-dev.tektona.ai, or set it directly via the --api-url flag, the TEKTONA_API_URL env var, or api_url in ~/.config/tektona/config.json. When set in more than one place the order is: flag, environment variable, config file. This deployment's endpoint is https://api-dev.tektona.ai. Setting the public-cloud endpoint (https://api.tektona.ai) clears the stored value so the built-in default keeps tracking.

API key. Pass it to tektona api-key set tektona_xxx, or run tektona api-key set with no argument to be prompted (input hidden). Inspect it with tektona api-key show (add --unmask for the full key). You can also pass --api-key per command or export TEKTONA_API_KEY. Resolution order: flag, env var, stored file.

Context. Resolved through a four-step chain (highest to lowest): --org / --project flags → TEKTONA_ORG / TEKTONA_PROJECT env vars → the repo-local .tektona/config.json at your git repository root (or the current directory when you're not in a git repo) → the global ~/.config/tektona/config.json. An explicitly empty env var (e.g. TEKTONA_ORG=) clears the value rather than falling through to a lower layer.

Config file format

The CLI keeps two files under ~/.config/tektona/, plus an optional repo-local file at your git repository root:

config.json schema:

{
  "api_url": "https://api-dev.tektona.ai",
  "org": "acme-corp",
  "project": "backend",
  "vnc": {
    "openBrowser": true
  },
  "update_check": true
}

All fields are optional. Set api_url to point the CLI at this deployment's endpoint (https://api-dev.tektona.ai). Commands that act on a project require both org and project from flags, environment variables, or this file.

The same schema is used at both scopes, but the repo-local .tektona/config.json is read for org, project, and vnc only. api_url, the API key, and update_check are global-only. They are never read from the repo-local file. api_url in particular stays global because it controls where your API key is sent, so a committed, repo-local file must not be able to redirect it.

Resize a sandbox

Change a sandbox's CPU, memory, or disk after it was created:

tektona sandbox resize <id> [--cpu N] [--memory N] [--disk N] [--force]

Only the flags you pass change. Anything you omit keeps its current value. The command prints the shape before and after the change.

# Give a sandbox more CPU and memory
tektona sandbox resize sbx_123 --cpu 4 --memory 8

# Grow the disk to 20 GiB
tektona sandbox resize sbx_123 --disk 20

# Shrink memory (requires --force)
tektona sandbox resize sbx_123 --memory 2 --force

The new shape is persisted immediately, but CPU and memory changes are not hot-plugged into a running VM — they take effect on the sandbox's next reboot (tektona sandbox reboot <id>, or a stop and start). A pause and resume does not apply them: resuming a hibernated or suspended sandbox restores it at the CPU and memory it had when it was paused, because the saved memory image is bound to that size. Disk can only grow, and downsizing memory needs --force because shrinking RAM can disrupt workloads relying on it. Live CPU/memory hot-plug and online disk growth are planned follow-ups.

Reboot a sandbox

Reboot a running sandbox by restarting its VM from the same disk.

tektona sandbox reboot <id> [-y]

This is an orderly reboot: the guest first shuts its processes down (they receive SIGTERM and get a few seconds to exit before SIGKILL) and flushes its filesystem, so in-memory state and running processes are lost but recently written files survive. A shutdown hook that needs longer than that short grace period won't finish. The disk is preserved. If the guest doesn't respond within a few seconds, the reboot falls back to a hard reset — the same as tektona sandbox reset — so a stuck sandbox can always be rebooted; in that case un-synced writes can be lost. Reboot is only valid while the sandbox is running, so resume a paused sandbox first.

tektona sandbox reboot 01JF...
tektona s reboot 01JF... -y   # skip confirmation

The command blocks until the VM is running again. Add -o json to get machine-readable output (requires -y).

Reset a sandbox

Hard-reset a running sandbox — like pulling the power.

tektona sandbox reset <id> [-y]

Unlike reboot, reset sends the guest no shutdown signal and does not flush the filesystem first, so recently written, un-synced files may be lost. Use it when a sandbox is unresponsive and won't shut down cleanly; otherwise prefer reboot. The disk and IP are preserved.

tektona sandbox reset 01JF...
tektona s reset 01JF... -y   # skip confirmation

Update notice

The CLI checks periodically for a newer version and prints a small notice when one is available. To disable, set TEKTONA_NO_UPDATE_CHECK=1 or add "update_check": false to ~/.config/tektona/config.json.

Global flags

Every command accepts these:

What's next