Settings and storage
The CLI keeps one session per environment in the OS keychain, and its other state in a configuration file. The companion choice is the only setting a command writes.
district settings companion
district settings companion [<name>]Chooses the companion that appears in command output. Without a name, the command asks, which needs a terminal. A caller with no terminal gets the stored choice on stdout, and is told once that the choice exists. district login offers the choice once, and Enter skips it.
The companion appears at most once per command, on stderr. It never appears in district git-credential, whose stderr reaches git.
Arguments
| Argument | Description |
|---|---|
[<name>] | The companion to use: sage, butter, senbei, or none. Without it, the command asks on a terminal and prints the stored choice without one. |
Output
$ district settings companion butter # choose Butter
$ district settings companion none # no companionExit codes
| Exit code | Meaning |
|---|---|
| 0 | The choice is stored, or the stored choice was printed. |
| 1 | The name is not one of the four choices. The stored choice does not change. |
Where the CLI stores things
| Item | Location |
|---|---|
| Session (refresh token, access token, email, organization id) | OS keychain, service district-cli, account production, staging, or dev |
| district-api origin overrides and the current environment | ${XDG_CONFIG_HOME:-~/.config}/district/config.json, mode 600 |
| Companion choice | the same config.json, under companion |
| Refresh lock | ${XDG_CONFIG_HOME:-~/.config}/district/session-<environment>.lock |
| Repository tokens that git received | OS keychain, service district-cli, account <environment>:repository-tokens |
A git operation calls district-api to mint a repository token when the keychain holds no token for the repository that is valid for 120 more seconds. The session record caches the access token, so a mint before expiry skips the WorkOS refresh. Two git operations that find the token expired refresh one at a time through the lock file, because the refresh token rotates on every call.
The CLI supports macOS and Linux. Windows Credential Manager limits a secret to 2560 bytes, which an access token can approach.