CLI configuration

2 min readUpdated 5 Sep 2026

tanomis resolves its configuration from three layers: flags on the command, environment variables, and a config file with named contexts. Flags win, then the environment, then the file.

The config file

tanomis searches from the working directory upward for .tanomis.yaml, then .cog.yaml at each level. If no repo config exists, it uses ~/.config/tanomis/config.yaml, falling back to ~/.config/cog/config.yaml when the new file is absent. --config PATH selects an explicit file. Configuration and cached credentials migrate to the new directory when each is next written; explicit file paths are respected. tanomis login creates a context.

current-context: saas
contexts:
  saas:
    auth-mode: oidc
    # endpoints discovered from the hosted console at login; no secret here

A context holds the environment’s endpoints, its authentication mode, and the selected workspace. It never holds a secret: cached credentials live separately, per context, and tanomis logout clears them while keeping the context.

Contexts

tanomis config current-context
tanomis config use-context staging
tanomis config view
tanomis config delete-context old

view prints the effective configuration after flags and environment are applied, which is the fastest way to see which environment a command will hit. Create a context by logging in to that environment with tanomis login --console URL --name NAME.

Authentication modes

Mode	Used for
`oidc`	The hosted device-authorization login a person completes in a browser. The hosted default.
`none`	Environments with no authentication; not applicable to hosted Tanomis.

For unattended use, tanomis exchanges an automation client’s ID and secret for a token when TANOMIS_API_URL, TANOMIS_CLIENT_ID, and TANOMIS_CLIENT_SECRET are set; no login mode is involved. See Automation credentials.

For human logins, access tokens are short-lived. Before an authenticated command, tanomis reuses a valid token or refreshes it; if the refresh grant is gone, the command stops and asks you to tanomis login again.

Environment variables

Variable	Effect
`TANOMIS_API_URL`	Public platform API origin for machine authentication and discovery.
`TANOMIS_CLIENT_ID`	Organization automation client ID. Use with `TANOMIS_CLIENT_SECRET`.
`TANOMIS_CLIENT_SECRET`	Automation client secret, injected from a secret manager. Never saved by machine login.
`TANOMIS_CA_BUNDLE`	CA bundle path for deployments with a private certificate authority.
`TANOMIS_TENANT`	Default for `--tenant` on tenant-scoped commands.
`TANOMIS_OUTPUT`	Default for `--output`: `table` or `json`.

Each TANOMIS_* CLI setting accepts its former COG_* name as a fallback when the new name is unset; using an old name emits one deprecation notice per process.

Other TANOMIS_* variables exist for internal endpoint and identity plumbing and are not part of the public contract.

With a human login, deploy and session-run commands refuse a --tenant that differs from the selected workspace, so the variable and the selection must agree. Machine authentication ignores cached human workspace and support context; choose an organization tenant explicitly, or let the sole/default ready tenant be selected.

Global flags

Flag	Effect
`--context NAME`	Use a context for this command without changing the current one.
`--tenant ID`	Tenant for tenant-scoped commands. Must match the selected workspace where one is selected.
`-o, --output table\|json`	Output format. Use `json` in scripts.
`--config PATH`	Config file path.
`--verbose`	Verbose output.

Every command page in the CLI reference lists these under Global flags.