Skip to content

Document CLI token auto-refresh and MINTLIFY_SESSION_TOKEN #5184

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

Closed
mintlify wants to merge 1 commit into from
+25 −2
Closed

Document CLI token auto-refresh and MINTLIFY_SESSION_TOKEN #5184

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
14 changes: 13 additions & 1 deletion cli/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,9 @@
mint login
```

Opens a browser window to complete authentication. If the browser does not open, the CLI displays a URL to open manually and a prompt to paste the authorization code. Credentials save in `~/.config/mintlify/config.json`.
Opens a browser window to complete authentication. If the browser does not open, the CLI displays a URL to open manually and a prompt to paste the authorization code. Credentials are stored securely in your operating system's keychain. When your access token expires, the CLI automatically refreshes it without requiring you to log in again.

Check warning on line 43 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L43 

In general, use active voice instead of passive voice ('are stored').

You can also authenticate using the `MINTLIFY_SESSION_TOKEN` environment variable for CI/CD or headless environments. See [Preview locally](/cli/preview#authenticate-with-an-environment-variable) for details.

---

Expand Down Expand Up @@ -106,7 +108,7 @@

| Flag | Description |
| --- | --- |
| `--query` | Filter by search query substring. |

Check warning on line 111 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L111 

Did you really mean 'substring'?
| `--page` | Filter by top clicked page. |

### `mint analytics feedback`
Expand Down Expand Up @@ -142,7 +144,7 @@
| --- | --- |
| `--page` | Filter conversations that reference a specific page in sources. |

#### `mint analytics conversation view <conversation-id>`

Check warning on line 147 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L147 

'````' should use sentence-style capitalization.

View a single conversation by ID. Use `mint analytics conversation list` to get IDs.

Expand All @@ -158,7 +160,7 @@
mint analytics conversation buckets list
```

#### `mint analytics conversation buckets view <bucket-id>`

Check warning on line 163 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L163 

'````' should use sentence-style capitalization.

View conversations in a category bucket. Use `mint analytics conversation buckets list` to get IDs.

Expand All @@ -176,7 +178,7 @@
mint config <subcommand> <key> [value]
```

| Subcommand | Description |

Check warning on line 181 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L181 

Use 'subcommands?' instead of 'Subcommand'.
| --- | --- |
| `set <key> <value>` | Set a configuration value. |
| `get <key>` | Display a configuration value. |
Expand Down Expand Up @@ -242,7 +244,7 @@
| `--local-schema` | Allow validation of locally hosted OpenAPI files served over HTTP. Only supports HTTPS in production. |

<Note>
The standalone `mint openapi-check` command is deprecated. Use `mint validate` instead.

Check warning on line 247 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L247 

In general, use active voice instead of passive voice ('is deprecated').
</Note>

---
Expand Down Expand Up @@ -328,7 +330,7 @@

## Telemetry

The CLI collects anonymous usage telemetry to help improve Mintlify. Telemetry data includes the command name, CLI version, operating system, and architecture. Mintlify does **not** collect personally identifiable information, project content, or file paths.

Check warning on line 333 in cli/commands.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/commands.mdx#L333 

Did you really mean 'informat'?

By default, the CLI collects telemetry data. You can opt out at any time using the `--telemetry` flag:

Expand All @@ -348,3 +350,13 @@
| `DO_NOT_TRACK` | `1` | Disable telemetry using the [Console Do Not Track](https://consoledonottrack.com/) standard. |

Your preference saves in `~/.config/mintlify/config.json` and persists across CLI sessions.

---

## Environment variables

| Variable | Description |
| --- | --- |
| `MINTLIFY_SESSION_TOKEN` | Authenticate the CLI without browser login. Useful for CI/CD pipelines and headless environments. The CLI uses keychain credentials first and falls back to this variable. |
| `MINTLIFY_TELEMETRY_DISABLED` | Set to `1` to disable anonymous telemetry. |
| `DO_NOT_TRACK` | Set to `1` to disable telemetry using the [Console Do Not Track](https://consoledonottrack.com/) standard. |
13 changes: 12 additions & 1 deletion cli/preview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
mint login
```

After you authenticate with the `mint login` command, the CLI stores your credentials in `~/.config/mintlify/config.json` so you stay logged in across sessions.
After you authenticate with the `mint login` command, the CLI stores your credentials securely in your operating system's keychain so you stay logged in across sessions. When your access token expires, the CLI automatically refreshes it in the background without requiring you to log in again.

Once logged in, run `mint dev` to start the local preview with search and the assistant enabled. The assistant uses the same indexed content as your deployed documentation site.

Expand All @@ -50,6 +50,17 @@
mint logout
```

### Authenticate with an environment variable

For CI/CD pipelines or headless environments where browser-based login is not available, set the `MINTLIFY_SESSION_TOKEN` environment variable:

```bash
export MINTLIFY_SESSION_TOKEN=your-token
mint dev
```

The CLI uses the keychain token first and falls back to `MINTLIFY_SESSION_TOKEN` if no keychain credentials are available or if the token cannot be refreshed.

Check warning on line 62 in cli/preview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

cli/preview.mdx#L62 

In general, use active voice instead of passive voice ('be refreshed').

## Custom ports

By default, the CLI uses port 3000. To use a different port, use the `--port` flag:
Expand Down
Loading