From 7123c507a7af6a9c9804ebfcec75d73a965b2e3c Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Wed, 30 Jul 2025 12:33:01 -0400 Subject: [PATCH] docs: LANGFLOW_ENABLE_SUPERUSER_CLI environment variable (#9223) * add-superuser-cli-note-and-env-var * code-review * env-var-link * resolve CLI superuser confusion --------- Co-authored-by: April M --- .../api-keys-and-authentication.mdx | 82 ++++----- docs/docs/Configuration/configuration-cli.mdx | 162 +++++++++--------- .../Configuration/environment-variables.mdx | 1 + 3 files changed, 118 insertions(+), 127 deletions(-) diff --git a/docs/docs/Configuration/api-keys-and-authentication.mdx b/docs/docs/Configuration/api-keys-and-authentication.mdx index 0cf2c4f7e..12b6e0368 100644 --- a/docs/docs/Configuration/api-keys-and-authentication.mdx +++ b/docs/docs/Configuration/api-keys-and-authentication.mdx @@ -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. @@ -51,57 +56,23 @@ The UI-generated key is appropriate for most cases. The CLI-generated key is nee -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" - ``` - -
- Result - - ```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", - } - ``` - -
- -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. + @@ -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. diff --git a/docs/docs/Configuration/configuration-cli.mdx b/docs/docs/Configuration/configuration-cli.mdx index 05b16a537..5341c9fe3 100644 --- a/docs/docs/Configuration/configuration-cli.mdx +++ b/docs/docs/Configuration/configuration-cli.mdx @@ -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 | |--------|---------|--------|-------------| | `--host` | `localhost` | String | The host on which the Langflow server will run. | | `--workers` | `1` | Integer | Number of worker processes. | @@ -109,9 +140,9 @@ python -m langflow run [OPTIONS] | `--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. | | `--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`
`info`
`warning`
`error`
`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. | -| `--cache` | `async` | `async`
`redis`
`memory`
`disk` | Type of cache to use. | +| `--cache` | `async` | Enum | Type of cache to use as one of `async`, `redis`, `memory`, or `disk`. | | `--frontend-path` | `./frontend` | String | Path to the frontend directory containing build files. This is for development purposes only. | | `--open-browser` | `true` | Boolean | Open the system web browser on startup. Use `--no-open-browser` to disable opening the system web browser on startup. | | `--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] | `--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). \ No newline at end of file diff --git a/docs/docs/Configuration/environment-variables.mdx b/docs/docs/Configuration/environment-variables.mdx index 47c849373..5450d33cc 100644 --- a/docs/docs/Configuration/environment-variables.mdx +++ b/docs/docs/Configuration/environment-variables.mdx @@ -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). |