Skip to content

docs: document CLI keyring-backed session storage #309

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document CLI keyring-backed session storage #309

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions cli/basic-usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,12 @@ porter app run my-app --cluster 67890 -- bash
```
</CodeGroup>

## Credential Storage

After `porter auth login`, your session tokens are stored in your operating system's secure credential store (macOS Keychain, Windows Credential Manager, GNOME Secret Service, or KWallet) rather than in `porter.yaml`. Tokens are automatically migrated from any older `porter.yaml` on your first run after upgrading.

For details on headless environments and the `PORTER_KEYRING_PASSWORD` fallback, see [`porter config`](/standard/cli/command-reference/porter-config#credential-storage).

## Environment Variables

Environment variables provide an alternative way to configure the CLI, which is especially useful in CI/CD pipelines.
Expand All @@ -100,6 +106,7 @@ Environment variables provide an alternative way to configure the CLI, which is
| `PORTER_TOKEN` | Authentication token | `--token` |
| `PORTER_HOST` | Custom Porter API host | `--host` |
| `PORTER_APP_NAME` | Default app name for commands | `--app` |
| `PORTER_KEYRING_PASSWORD` | Password for the encrypted keyring file used in headless environments | — |

<Info>
Environment variables take precedence over values in your config file, but flags take precedence over environment variables.
Expand Down
30 changes: 29 additions & 1 deletion standard/cli/command-reference/porter-config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,16 @@ porter config

| Flag | Description |
|------|-------------|
| `--show-token` | Display the CLI authentication token in the output. By default, the token is hidden for security. Pass this flag to reveal the token value. |
| `--show-token` | Display the CLI authentication token and session credentials in the output. By default, tokens are hidden for security. Pass this flag to reveal the values. |

<Info>
Configuration values can be overridden using flags or environment variables. See [Basic Usage](/cli/basic-usage) for details.
</Info>

<Note>
Session tokens for browser-based logins are stored in your operating system's secure credential store (macOS Keychain, Windows Credential Manager, GNOME Keyring/Secret Service, or KWallet) rather than in `porter.yaml`. The `--show-token` flag reads these values from the keyring and prints them alongside the rest of your configuration.
</Note>

---

## `porter config set-project`
Expand Down Expand Up @@ -76,3 +80,27 @@ Porter stores configuration in `~/.porter/config.json`. You can also override se
| `PORTER_CLUSTER` | Override cluster ID |
| `PORTER_TOKEN` | Override authentication token |
| `PORTER_HOST` | Override API host |

## Credential Storage

When you log in with `porter auth login`, the CLI stores your session tokens in your operating system's secure credential store:

| Platform | Backend |
|----------|---------|
| macOS | Keychain |
| Windows | Credential Manager (wincred) |
| Linux (GNOME) | Secret Service / libsecret |
| Linux (KDE) | KWallet |
| Headless / fallback | Encrypted file at `~/.porter/keyring` |

If you previously logged in with an older CLI version that wrote session tokens to `porter.yaml`, those tokens are automatically migrated to the keyring on the next run and removed from the YAML file.

### Headless environments

On systems without a native credential store (for example, CI containers or headless servers), Porter falls back to an encrypted file at `~/.porter/keyring`. Set `PORTER_KEYRING_PASSWORD` to control the password used to encrypt that file:

```bash
export PORTER_KEYRING_PASSWORD="your-strong-password"
```

If the variable is unset, a non-interactive default is used so token refresh can run without a TTY prompt.