jyapayne/langflow
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: LANGFLOW_ENABLE_SUPERUSER_CLI environment variable (#9223)

Browse source 
* add-superuser-cli-note-and-env-var

* code-review

* env-var-link

* resolve CLI superuser confusion

---------

Co-authored-by: April M <april.murphy@datastax.com>
This commit is contained in:
Mendon Kissling 2025-07-30 12:33:01 -04:00 • committed by GitHub
commit 7123c507a7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 118 additions and 127 deletions
Download patch file Download diff file Expand all files Collapse all files

82
docs/docs/Configuration/api-keys-and-authentication.mdx
View file

@ -25,20 +25,25 @@ There are three types of credentials that you use in Langflow:
You can use Langflow API keys to interact with Langflow programmatically.
A Langflow API key has the same permissions and access as the user who created it.
This means your API key can only access your own flows, components, and database.
You cannot access other users' resources with your own Langflow API keys.
If you create a key as a superuser, then that key has superuser privileges within your Langflow server.
In Langflow version 1.5 and later, most API endpoints require a Langflow API key, even when `AUTO_LOGIN` is `True`.
In Langflow version 1.5 and later, most API endpoints require a Langflow API key, even when `LANGFLOW_AUTO_LOGIN` is `True`.
For more information, see [`LANGFLOW_AUTO_LOGIN`](#langflow-auto-login).
### Langflow API key permissions
A Langflow API key adopts the privileges of the user who created it.
This means that API keys you create have the same permissions and access that you do, including access to your flows, components, and Langflow database.
A Langflow API key cannot be used to access resources outside of your own Langflow server.
In single-user environments, you are always a superuser, and your Langflow API keys always have superuser privileges.
In multi-user environments, users who aren't superusers cannot use their API keys to access other users' resources.
You must [start your Langflow server with authentication enabled](#start-a-langflow-server-with-authentication-enabled) to allow user management and creation of non-superuser accounts.
### Create a Langflow API key
You can generate a Langflow API key with the UI or the CLI.
The UI-generated key is appropriate for most cases. The CLI-generated key is needed when your Langflow server is running in `--backend-only` mode.
The UI-generated key is appropriate for most development use cases. The CLI-generated key is needed when your Langflow server is running in `--backend-only` mode.
<Tabs>
<TabItem value="Langflow UI" label="Langflow UI" default>
@ -51,57 +56,23 @@ The UI-generated key is appropriate for most cases. The CLI-generated key is nee
</TabItem>
<TabItem value="Langflow CLI" label="Langflow CLI">
If you're serving your flow with `--backend-only=true`, you can't create API keys in the UI, because the frontend is not running.
If you're serving your flow with `--backend-only=true`, you can't create API keys in the UI because the frontend isn't running.
In this case, you must create API keys with the Langflow CLI.
Depending on your authentication settings, note the following requirements for creating API keys with the Langflow CLI:
1. Recommended: [Start your Langflow server with authentication enabled](#start-a-langflow-server-with-authentication-enabled).
* If `AUTO_LOGIN` is `FALSE`, you must be logged in as a superuser.
* If `AUTO LOGIN` is `TRUE`, you're already logged in as superuser.
This configuration is recommended for security reasons to prevent unauthorized API key and superuser creation, especially in production environments.
To create an API key for a user from the CLI, do the following:
However, if authentication isn't enabled (`LANGFLOW_AUTO_LOGIN=True`), all users are effectively superusers, and they can create API keys with the Langflow CLI.
1. In your `.env` file, set `AUTO_LOGIN=FALSE`, and set superuser credentials for your server.
```text
LANGFLOW_AUTO_LOGIN=False
LANGFLOW_SUPERUSER=administrator
LANGFLOW_SUPERUSER_PASSWORD=securepassword
```
2. To confirm your superuser status, call [`GET /users/whoami`](/api-users#get-current-user), and then check that the response contains `"is_superuser": true`:
```bash
curl -X GET \
"$LANGFLOW_URL/api/v1/users/whoami" \
-H "accept: application/json" \
-H "x-api-key: $LANGFLOW_API_KEY"
```
<details>
<summary>Result</summary>
```json
{
"id": "07e5b864-e367-4f52-b647-a48035ae7e5e",
"username": "langflow",
"profile_image": null,
"store_api_key": null,
"is_active": true,
"is_superuser": true,
"create_at": "2025-05-08T17:59:07.855965",
"updated_at": "2025-05-29T15:06:56.157860",
"last_login_at": "2025-05-29T15:06:56.157016",
}
```
</details>
3. Create an API key:
2. Create an API key with [`langflow api-key`](/configuration-cli#langflow-api-key):
```shell
uv run langflow api-key
```
All API keys created with the Langflow CLI have superuser privileges because the command requires superuser authentication, and Langflow API keys adopt the privileges of the user who created them.
</TabItem>
</Tabs>
@ -278,6 +249,12 @@ LANGFLOW_NEW_USER_IS_ACTIVE=False
For more information, see [Start a Langflow server with authentication enabled](#start-a-langflow-server-with-authentication-enabled).
### LANGFLOW_ENABLE_SUPERUSER_CLI {#langflow-enable-superuser-cli}
Controls the availability of the `langflow superuser` command in the Langflow CLI.
The default is `True`, but `False` is recommended to prevent unrestricted superuser creation.
For more information, see [`langflow superuser`](/configuration-cli#langflow-superuser).
## Start a Langflow server with authentication enabled
This section shows you how to use the [authentication environment variables](/api-keys-and-authentication#authentication-environment-variables) to deploy a Langflow server with authentication enabled.
@ -298,6 +275,7 @@ Additionally, you must sign in as a superuser to manage users and [create a Lang
LANGFLOW_SUPERUSER_PASSWORD=
LANGFLOW_SECRET_KEY=
LANGFLOW_NEW_USER_IS_ACTIVE=False
LANGFLOW_ENABLE_SUPERUSER_CLI=False
```
Your `.env` file can have other environment variables.
@ -322,6 +300,7 @@ Additionally, you must sign in as a superuser to manage users and [create a Lang
LANGFLOW_SUPERUSER_PASSWORD=securepassword
LANGFLOW_SECRET_KEY=dBuu...2kM2_fb
LANGFLOW_NEW_USER_IS_ACTIVE=False
LANGFLOW_ENABLE_SUPERUSER_CLI=False
```
5. Start Langflow with the configuration from your `.env` file:
@ -330,6 +309,9 @@ Additionally, you must sign in as a superuser to manage users and [create a Lang
uv run langflow run --env-file .env
```
Starting Langflow with an `.env` file automatically authenticates you as the superuser set in `LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD`.
If you don't explicitly set these variables, the default values are `langflow` and `langflow`.
6. Verify the server is running. The default location is `http://localhost:7860`.
Next, you can add users to your Langflow server to collaborate with others on flows.

162
docs/docs/Configuration/configuration-cli.mdx
View file

@ -7,73 +7,105 @@ import Link from '@docusaurus/Link';
The Langflow command line interface (Langflow CLI) is the main interface for managing and running the Langflow server.
## Precedence
Langflow CLI options override the values of [environment variables](/environment-variables) set in your terminal or primary `.env` file.
For example, if you have `LANGFLOW_PORT=7860` defined as an environment variable, and you run the CLI with `--port 7880`, then Langflow sets the port to `7880` because the CLI option overrides the environment variable.
This also applies to Boolean environment variables.
For example, if your set `LANGFLOW_REMOVE_API_KEYS=True` in your `.env` file, then you can change this to `False` by running the CLI with `--no-remove-api-keys`.
## Options
All Langflow CLI commands support options that modify the command's behavior or set environment variables.
### Option syntax
To set values for options, you can use either of the following syntax styles:
* `--option value`
* `--option=value`
Values with spaces must be surrounded by quotation marks:
* `--option 'Value with Spaces'`
* `--option="Value with Spaces"`
### Boolean forms
Boolean options enable and disable settings.
They accept no value.
Instead, each Boolean option has a true (enabled) and false (disabled) form:
* Enabled (true): `--option`
* Disabled (false): `--no-option`
For example, `--remove-api-keys` is equivalent to `LANGFLOW_REMOVE_API_KEYS=True`:
```bash
langflow run --remove-api-keys
```
In contrast, `--no-remove-api-keys` is equivalent to `LANGFLOW_REMOVE_API_KEYS=False`:
```bash
langflow run --no-remove-api-keys
```
### Default options
The following options are available for all Langflow CLI commands:
* `--install-completion`: Install auto-completion for the current shell.
* `--show-completion`: Show the location of the auto-completion config file, if installed.
* `--help`: Print information about command usage, options, and arguments.
These are modifiers that change the output or execution of a command.
They aren't Booleans, and they accept no values.
## CLI commands
The following sections describe the available CLI commands and their options.
The following sections describe the available CLI commands and any non-default options available for each command.
### langflow
Running the CLI without any arguments displays a list of available options and commands.
Running the CLI without any arguments prints a list of available options and commands:
```bash
langflow [OPTIONS]
langflow
# or
python -m langflow [OPTIONS]
python -m langflow
```
#### Options
### langflow api-key {#langflow-api-key}
| Option | Default | Values | Description |
|--------|---------|--------|-------------|
| `--install-completion` | *Not applicable* | *Not applicable* | Install auto-completion for the current shell. |
| `--show-completion` | *Not applicable* | *Not applicable* | Show the location of the auto-completion config file, if installed. |
| `--help` | *Not applicable* | *Not applicable* | Display information about the command usage and its options and arguments. |
### langflow api-key
To create API keys with the Langflow CLI, `AUTO_LOGIN` must be set to `TRUE`, or you must be logged in as a superuser.
* If `AUTO_LOGIN` is `FALSE`, you must be logged in as a superuser.
* If `AUTO LOGIN` is `TRUE`, you're already logged in as superuser.
For more information, see [API keys and authentication](/api-keys-and-authentication).
Create a Langflow API key with superuser privileges.
For more information, see [Langflow API keys](/api-keys-and-authentication#langflow-api-keys).
```bash
langflow api-key [OPTIONS]
langflow api-key
# or
uv run langflow api-key [OPTIONS]
uv run langflow api-key
```
#### Options
| Option | Default | Values | Description |
|--------|---------|--------|-------------|
| `--install-completion` | *Not applicable* | *Not applicable* | Install auto-completion for the current shell. |
| `--show-completion` | *Not applicable* | *Not applicable* | Show the location of the auto-completion config file (if installed). |
| `--help` | *Not applicable* | *Not applicable* | Display information about the command usage and its options and arguments. |
### langflow copy-db
Copy the database files to the current directory, which is the directory containing `__main__.py`.
Copy the Langflow database files from the cache directory to the current directory containing `__main__.py`.
You can find this directory by running `which langflow`.
Copy the Langflow database files, `langflow.db` and `langflow-pre.db` (if they exist), from the cache directory to the current directory.
```bash
langflow copy-db
# or
python -m langflow copy-db
```
#### Options
| Option | Default | Values | Description |
|--------|---------|--------|-------------|
| `--help` | *Not applicable* | *Not applicable* | Display information about the command usage and its options and arguments. |
The database files are `langflow.db` and `langflow-pre.db`.
If these files don't exist in the cache directory, then nothing is copied.
### langflow migration
Run or test database migrations.
Run or test database migrations:
```bash
langflow migration [OPTIONS]
@ -83,11 +115,10 @@ python -m langflow migration [OPTIONS]
#### Options
| Option | Default | Values | Description |
| Option | Default | Type | Description |
|--------|---------|--------|-------------|
| `--test` | `true` | Boolean | Run migrations in test mode. Use `--no-test` to disable test mode. |
| `--fix` | `false` (`--no-fix`) | Boolean | Fix migrations. This is a destructive operation, and all affected data will be deleted. Only use this option if you know what you are doing. |
| `--help` | *Not applicable* | *Not applicable* | Display information about the command usage and its options and arguments. |
### langflow run
@ -101,7 +132,7 @@ python -m langflow run [OPTIONS]
#### Options
| Option | Default | Values | Description |
| Option | Default | Type | Description |
|--------|---------|--------|-------------|
| <Link id="run-host"/>`--host` | `localhost` | String | The host on which the Langflow server will run. |
| <Link id="run-workers"/>`--workers` | `1` | Integer | Number of worker processes. |
@ -109,9 +140,9 @@ python -m langflow run [OPTIONS]
| <Link id="run-port"/>`--port` | `7860` | Integer | The port on which the Langflow server will run. The server automatically selects a free port if the specified port is in use. |
| <Link id="run-components-path"/>`--components-path` | `langflow/components` | String | Path to the directory containing custom components. |
| `--env-file` | Not set | String | Path to the `.env` file containing environment variables. |
| `--log-level` | `critical` | `debug`<br/>`info`<br/>`warning`<br/>`error`<br/>`critical` | Set the logging level. |
| `--log-level` | `critical` | Enum | Set the logging level as one of `debug`, `info`, `warning`, `error`, or `critical`. |
| `--log-file` | `logs/langflow.log` | String | Set the path to the log file for Langflow. |
| <Link id="run-cache"/>`--cache` | `async` | `async`<br/>`redis`<br/>`memory`<br/>`disk` | Type of cache to use. |
| <Link id="run-cache"/>`--cache` | `async` | Enum | Type of cache to use as one of `async`, `redis`, `memory`, or `disk`. |
| <Link id="run-frontend-path"/>`--frontend-path` | `./frontend` | String | Path to the frontend directory containing build files. This is for development purposes only. |
| <Link id="run-open-browser"/>`--open-browser` | `true` | Boolean | Open the system web browser on startup. Use `--no-open-browser` to disable opening the system web browser on startup. |
| <Link id="run-remove-api-keys"/>`--remove-api-keys` | `false` (`--no-remove-api-keys`) | Boolean | Remove API keys from the projects saved in the database. |
@ -123,14 +154,19 @@ python -m langflow run [OPTIONS]
| <Link id="run-max-file-size-upload"/>`--max-file-size-upload` | `100` | Integer | Set the maximum file size for the upload in megabytes. |
| `--ssl-cert-file-path` | Not set | String | Path to the SSL certificate file on the local system. |
| `--ssl-key-file-path` | Not set | String | Path to the SSL key file on the local system. |
| `--help` | *Not applicable* | *Not applicable* | Display information about the command usage and its options and arguments. |
For information about the environment variables that correspond to these options, see [Supported environment variables](/environment-variables#supported-variables).
### langflow superuser
### langflow superuser {#langflow-superuser}
Create a superuser account.
Controlled by the [`LANGFLOW_ENABLE_SUPERUSER_CLI`](/api-keys-and-authentication#langflow-enable-superuser-cli) environment variable:
* **`LANGFLOW_ENABLE_SUPERUSER_CLI=True` (Default)**: The `langflow superuser` command is available, and superuser creation is unrestricted.
* **`LANGFLOW_ENABLE_SUPERUSER_CLI=False` (Recommended)**: Disables the `langflow superuser` command.
For security reasons, this is recommended to prevent unauthorized superuser creation, especially in production environments.
```bash
langflow superuser [OPTIONS]
# or
@ -139,37 +175,9 @@ python -m langflow superuser [OPTIONS]
#### Options
| Option | Default | Values | Description |
| Option | Default | Type | Description |
|--------|---------|--------|-------------|
| `--username` | Required | String | Specify the name for the superuser. |
| `--password` | Required | String | Specify the password for the superuser. |
| `--username` | `langflow` | String | Specify the name for the superuser. |
| `--password` | `langflow` | String | Specify the password for the superuser. |
For more information about these values, see [`LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD`](/api-keys-and-authentication#langflow-superuser).
## Precedence
Langflow CLI options override the values of [environment variables](/environment-variables) set in your terminal or primary `.env` file.
For example, if you have `LANGFLOW_PORT=7860` defined as an environment variable, but you run the CLI with `--port 7880`, Langflow sets the port to **`7880`**, the value passed with the CLI.
## Assign values
There are two ways you can assign a value to a CLI option.
You can write the option flag and its value with a single space between them: `--option value`.
Or, you can write them using an equals sign (`=`) between the option flag and the value: `--option=value`.
Values that contain spaces must be surrounded by quotation marks: `--option 'Value with Spaces'` or `--option='Value with Spaces'`.
### Boolean values {#boolean}
Boolean options turn a behavior on or off, and therefore accept no arguments.
To activate a boolean option, type it on the command line.
For example:
```bash
langflow run --remove-api-keys
```
All boolean options have a corresponding option that negates it.
For example, the negating option for `--remove-api-keys` is `--no-remove-api-keys`.
These options let you negate boolean options that you may have set in your primary `.env` [environment variables](/environment-variables).
For more information, see [`LANGFLOW_SUPERUSER` and `LANGFLOW_SUPERUSER_PASSWORD`](/api-keys-and-authentication#langflow-superuser).

1
docs/docs/Configuration/environment-variables.mdx
View file

@ -163,6 +163,7 @@ The following table lists the environment variables supported by Langflow.
| `LANGFLOW_DB_CONNECTION_SETTINGS` | JSON | Not set | A JSON dictionary to centralize database connection parameters. Example: `{"pool_size": 10, "max_overflow": 20}` |
| `LANGFLOW_DISABLE_TRACK_APIKEY_USAGE` | Boolean | `false` | If set to `true`, disables tracking of API key usage (`total_uses` and `last_used_at`) to avoid database contention under high concurrency. |
| `LANGFLOW_ENABLE_LOG_RETRIEVAL` | Boolean | `false` | Enable log retrieval functionality. |
| `LANGFLOW_ENABLE_SUPERUSER_CLI` | Boolean | `true` | Allow creation of superusers with the Langflow CLI. Recommended to be `false` in production for security reasons. See [`langflow superuser`](./configuration-cli.mdx#superuser). |
| `LANGFLOW_FALLBACK_TO_ENV_VAR` | Boolean | `true` | If enabled, [global variables](/configuration-global-variables) set in the Langflow UI fall back to an environment variable with the same name when Langflow fails to retrieve the variable value. |
| `LANGFLOW_FRONTEND_PATH` | String | `./frontend` | Path to the frontend directory containing build files. This is for development purposes only. See [`--frontend-path`](./configuration-cli.mdx#run-frontend-path). |
| `LANGFLOW_HEALTH_CHECK_MAX_RETRIES` | Integer | `5` | Set the maximum number of retries for the health check. See [`--health-check-max-retries`](./configuration-cli.mdx#run-health-check-max-retries). |