---
title: Contexts and settings
description: Choose the organization, workspace, environment and Titan
  deployment hexel works in, change output formats, and configure hexel with
  environment variables.
url: https://hexelstudio.com/docs/cli/contexts
---

## 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.

```bash
hexel context set --org org_123 --workspace ws_456 --env env_789
hexel context set --deployment td-0123456789abcdef
hexel context show
```

Keep several contexts and switch between them, for example one per organization:

```bash
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 staging
```

### Override 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.

```bash
hexel workspace list --org org_999
HEXEL_CONTEXT=staging hexel titan session list
```

## Output

Every command takes `-o` (`--output`): `table` (the default), `json` or `yaml`. `json` and `yaml` print the full API response, with every field, for scripts:

```bash
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 |