---

name: using-streamlit-cli description: Documents Streamlit CLI commands for running apps, managing configuration, and diagnostics. Use when starting Streamlit apps, configuring runtime options, or troubleshooting CLI issues.

Using the Streamlit CLI

The Streamlit CLI is the primary tool for running Streamlit applications and managing configuration. This skill covers all essential commands and configuration options.

Running Streamlit apps

Basic syntax

Copystreamlit run [<entrypoint>] [-- config options] [script args]

Entrypoint options

Examples

Copy# Run default app in current directory
streamlit run

# Run a specific file
streamlit run app.py

# Run from a URL
streamlit run https://raw.githubusercontent.com/streamlit/demo-uber-nyc-pickups/master/streamlit_app.py

# Alternative: run as Python module (useful for IDE configuration)
python -m streamlit run app.py

Running with uv (recommended)

Use uv run to run Streamlit in a virtual environment with automatic dependency management:

Copy# Run with uv (automatically uses/creates virtual environment)
uv run streamlit run app.py

# With configuration options
uv run streamlit run app.py --server.headless=true

# With script arguments
uv run streamlit run app.py -- arg1 arg2

Using uv run is the recommended approach because it:

• Automatically manages virtual environments
• Resolves and installs dependencies from pyproject.toml
• Ensures reproducible environments across machines
• Avoids manual activation/deactivation of virtual environments

Setting configuration with streamlit run

Configuration options follow the pattern --<section>.<option>=<value> and must come after the script name.

Recommendation: For persistent configuration, use .streamlit/config.toml in your project directory instead of command-line flags. This keeps your run command simple and makes configuration easier to manage and share with your team.

Examples

Copystreamlit run app.py --server.port=8080
streamlit run app.py --server.headless=true
streamlit run app.py --server.runOnSave=true
streamlit run app.py --server.address=0.0.0.0
streamlit run app.py --client.showErrorDetails=false
streamlit run app.py --theme.primaryColor=blue

Combining multiple options

Copystreamlit run app.py \
    --server.port=8080 \
    --server.headless=true \
    --theme.primaryColor=blue \
    --client.showErrorDetails=false

Passing arguments to your script

Script arguments come after configuration options. Use sys.argv to access them:

Copystreamlit run app.py -- arg1 arg2 "arg with spaces"

In your script:

Copyimport sys

# sys.argv[0] = script path
# sys.argv[1:] = your arguments
args = sys.argv[1:]

Other CLI commands

View configuration

Copy# Show all current configuration settings
streamlit config show

Cache management

Copy# Clear all cached data from disk
streamlit cache clear

Diagnostics and help

Copy# Show installed version
streamlit version

# List all available commands
streamlit help

# Open documentation in browser
streamlit docs

Project scaffolding

Copy# Create starter files for a new project
streamlit init

Demo app

Copy# Launch the Streamlit demo application
streamlit hello

Configuration precedence

Configuration can be set in multiple places. Order of precedence (highest to lowest):

1. Command-line flags (--server.port=8080)
2. Environment variables (STREAMLIT_SERVER_PORT=8080)
3. Local config (.streamlit/config.toml in project directory)
4. Global config (~/.streamlit/config.toml)

References

• Run your app - Concepts and methods for running Streamlit apps
• config.toml - Complete configuration options reference
• CLI reference - Full CLI command documentation