Contexts and settings
Choose the organization, workspace, environment and Titan deployment hexel works in, change output formats, and configure hexel with environment variables.
On this page
Contexts
A context names what commands act on: an organization, a workspace, an environment and a Titan deployment. hexel starts with one context, default. Each field is optional; set the ones you use.
hexel context set --org org_123 --workspace ws_456 --env env_789
hexel context set --deployment td-0123456789abcdef
hexel context showKeep several contexts and switch between them, for example one per organization:
hexel context set --org org_123 # sets the current context
hexel context use staging # switch to (or create) the context "staging"
hexel context set --org org_999
hexel context list # * marks the current one
hexel context delete stagingOverride for one command
A flag or an environment variable overrides the context for one command, without changing it:
| Flag | Variable | Overrides |
|---|---|---|
--context | HEXEL_CONTEXT | Which context to use |
--org | HEXEL_ORG | Organization |
--workspace | HEXEL_WORKSPACE | Workspace |
--env | HEXEL_ENV | Environment |
--deployment (on hexel titan) | HEXEL_DEPLOYMENT | Titan deployment |
A flag wins over a variable, which wins over the context.
hexel workspace list --org org_999
HEXEL_CONTEXT=staging hexel titan session listOutput
Every command takes -o (--output): table (the default), json or yaml. json and yaml print the full API response, with every field, for scripts:
hexel titan approval list -o json | jq -r '.items[].approval_request_id'Tables show the main fields, shorten long values and show times in your local time zone. hexel titan deployment list leaves out retired deployments in every format; add --all to include them.
Confirmations
Permanent actions, such as hexel titan session revoke, hexel titan kill and hexel titan deployment retire, ask you to type yes first. Pass --yes (-y) to skip the question. When hexel isn't running in a terminal, for example in CI, these commands fail unless you pass --yes.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | The command failed; the error is printed on standard error, with a hint when there is one |
2 | The command was called wrongly (a missing argument, an unknown flag or command); hexel prints the usage line and an example |
4 | Not signed in: run hexel auth login, or set HEXEL_API_KEY |
Settings file
hexel keeps its settings, including the contexts, in config.json in its settings directory. Stored credentials go in the OS keychain, or in credentials.json in the same directory when there is no keychain.
| System | Directory |
|---|---|
| Linux | ~/.config/hexel (or $XDG_CONFIG_HOME/hexel) |
| macOS | ~/Library/Application Support/hexel |
| Windows | %AppData%\hexel |
Set HEXEL_CONFIG_DIR to use another directory, for example to keep a separate setup for a test.
hexel config view shows the settings file's location and the endpoints hexel uses.
Environment variables
| Variable | Use |
|---|---|
HEXEL_API_KEY | A service user's API key, exchanged for an access token on each run and never stored |
HEXEL_TOKEN | An access token, used as is |
HEXEL_CONTEXT, HEXEL_ORG, HEXEL_WORKSPACE, HEXEL_ENV, HEXEL_DEPLOYMENT | Override the context (see above) |
HEXEL_CONFIG_DIR | Settings directory |
HEXEL_NO_UPDATE_CHECK | Don't check for a newer release |