Context & config
How the tektona CLI resolves the active org/project, the two config scopes (global and repo-local), the credential boundary, and every env var and flag.
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
tektona env -- npm start # run code with the resolved context (see below)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.jsonResolution order
Org and project are each resolved independently through this chain, highest to lowest:
--org/--projectflagsTEKTONA_ORG/TEKTONA_PROJECTenvironment variables- the repo-local
.tektona/config.json(at the git repository root) - 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
tektonain 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.jsonwill 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.
Commit .tektona/config.json so the binding travels with the repo. It only
ever contains names (org, project) and the non-secret vnc preference,
never your API key.
Config file format
| File | Permissions | Purpose |
|---|---|---|
~/.config/tektona/api_key | 0600 | The raw API key string. Plain text. |
~/.config/tektona/config.json | 0600 | Global context and per-feature settings. |
.tektona/config.json (repo root) | 0644 | Committed project binding. Only org, project, and vnc are read from it. |
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_urlcontrols 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_checkis a machine-level preference, not a project property.
Use the context in SDKs and scripts
The SDKs read the same settings from environment variables: TEKTONA_API_KEY,
TEKTONA_API_URL, TEKTONA_ORG and TEKTONA_PROJECT. tektona env resolves
them through the chain above and hands them to your code, so a script uses the
same org and project as the CLI in that folder.
tektona env -- npm start # run one command with the variables set
tektona env --project staging -- npm test # flags override as usual
eval "$(tektona env)" # set them in the current shell (bash, zsh)
tektona env --shell fish | source # fish
tektona env --shell powershell | Invoke-Expression # PowerShell (Windows)Both ways set the same variables. Use tektona env -- <command> for one
command, in scripts and in CI: the API key goes only into that process's
environment and is never printed, and the command's exit code is passed on. Use
eval in an interactive shell when you run many commands with the same context.
A program cannot change the environment of the shell that started it, so
tektona env on its own only prints the export lines. Use eval to apply
them. After eval, the variables override the repo-local file for every later
tektona command in that shell, also after a cd into another repo or a
tektona ctx set. Open a new shell, or unset them, to go back.
To load a folder's context automatically with direnv, add
these lines to its .envrc. watch_file reloads it when ctx set changes the
binding:
watch_file .tektona/config.json
eval "$(tektona env)"-o json prints the same values as JSON.
The printed output contains your API key. In a terminal the key is masked, and
the full key is written only into a pipe. A pipe into less, tee or a log
file, and set -x in a script, show it. Use tektona env -- <command> there.
Environment variables & flags
| Setting | Flag | Env var | Notes |
|---|---|---|---|
| Organization | --org | TEKTONA_ORG | Empty env value clears it |
| Project | --project | TEKTONA_PROJECT | Empty env value clears it |
| API URL | --api-url | TEKTONA_API_URL | Global config / built-in default otherwise |
| API key | --api-key | TEKTONA_API_KEY | Falls back to the stored key file |
| Config dir | (none) | TEKTONA_CONFIG_DIR | Overrides ~/.config/tektona |
| Update check | (none) | TEKTONA_NO_UPDATE_CHECK | Set to disable the version notice |
Flags and environment variables are per-invocation overrides, ideal for
direnv or one-off commands, and always win over both config files.