Context & config

Every sandbox command runs against a single organization and project, together the context. The CLI resolves that context (and a few related settings) from flags, environment variables, and two config files. This page is the full reference. For first-time setup start with the Tektona CLI overview.

Commands

tektona ctx show            # print the resolved context and where each value came from
tektona ctx set             # interactive picker (needs an API key)
tektona ctx set acme/backend        # set non-interactively (qualified ref)
tektona ctx set acme backend        # set non-interactively (two arguments)
tektona ctx set --global acme/backend   # write the machine-wide default
tektona ctx list            # list every org/project your key can reach

ctx show annotates each value with its source, so you can always tell why a command will act where it does:

Org:     acme-corp            (local)
Project: backend              (local)
API:     https://api-dev.tektona.ai (global)
Local:   /path/to/repo/.tektona/config.json

Resolution order

Org and project are each resolved independently through this chain, highest to lowest:

1. --org / --project flags
2. TEKTONA_ORG / TEKTONA_PROJECT environment variables
3. the repo-local .tektona/config.json (at the git repository root)
4. the global ~/.config/tektona/config.json

An explicitly empty environment variable (e.g. TEKTONA_ORG=) clears the value rather than falling through to a lower layer, useful for scoping a single shell.

The two scopes

Global: ~/.config/tektona/config.json

Your machine-wide default, written by tektona login and tektona ctx set --global. Use it for the project you work in most often.

Repo-local: .tektona/config.json

A small, committed file that binds a repository to an org/project, so a clone already knows its context. tektona ctx set (without --global) writes it.

It is anchored at the git repository root, the toplevel of your repo or worktree, and is used from any subdirectory. Discovery never searches above the repo root, which is what makes it safe for parallel work:

• Each checkout or git worktree carries its own binding, so multiple agents running tektona in different repos never clobber each other's context.
• A context can never bleed in from a directory above the repo (e.g. a stray ~/work/.tektona/config.json will not apply to repos beneath it).

Outside a git repository, the current directory is used as the anchor. Running tektona ctx set directly in your home directory is refused (a config there would just be a second global). Use --global instead.

Config file format

Both config.json files share one schema (all fields optional):

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

What the repo-local file may set

Only org, project, and vnc are read from .tektona/config.json. A key present locally overrides the global value (even when empty, which clears it). The vnc block is replaced wholesale.

api_url, the API key, and update_check are global-only and are ignored if they appear in a repo-local file (ctx show flags them as ignored). This is a deliberate credential/preference boundary:

• api_url controls where your API key is sent. If a committed, repo-local file could redirect it, cloning a malicious repo could leak your key to an attacker, so it stays global-only.
• The API key is a secret and never belongs in a committed file.
• update_check is a machine-level preference, not a project property.

Environment variables & flags

Flags and environment variables are per-invocation overrides, ideal for direnv or one-off commands, and always win over both config files.