Quick Start
Get from zero to your first agent turn in under 5 minutes.
Prerequisites
Python 3.10+ and an OpenAI-compatible API key. Recommended: OpenRouter (free tier, no card for most models) or Google AI Studio for Gemini.
Step 1 — Set up your API key
Create a .env file in your workspace root:
.envbash
Flux-CLI loads these automatically via python-dotenv. You can also set them in your shell.
API_KEY=your_api_key_here
BASE_URL=https://openrouter.ai/api/v1
# Gemini example:
# BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
# model: gemini-3-flash-previewStep 2 — Launch the REPL
Interactive modebash
Starts the interactive REPL. You'll see the gradient ASCII banner on launch.
cd your-project
python main.py
# or if installed:
# flux██╗ ███████╗██╗ ██╗ ██╗██╗ ██╗
╚██╗ ██╔════╝██║ ██║ ██║╚██╗██╔╝
╚██╗ █████╗ ██║ ██║ ██║ ╚███╔╝
██╔╝ ██╔══╝ ██║ ██║ ██║ ██╔██╗
██╔╝ ██║ ███████╗╚██████╔╝██╔╝ ██╗
╚═╝ ╚═╝ ╚══════╝ ╚═════╝ ╚═╝ ╚═╝Tip
Run flux config for an interactive wizard that writes ~/.config/flux-cli/config.toml for you.
Step 3 — Try your first prompt
REPLtext
Flux will stream its reasoning and call list_dir under the hood.
❯ What files are in the current directory?You'll see:
- Streamed reasoning — tokens appear in real time
- Tool call —
list_dirfires with parameters - Panel output — results rendered with syntax highlight
Step 4 — Slash commands
Slash commandstext
Quick controls without leaving the REPL.
❯ /help # help dashboard
❯ /config # active configuration
❯ /stats # token & turn metrics
❯ /tools # available tools
❯ /clear # clear history
❯ /exit # quitStep 5 — Single-command mode
Great for CI or scripting:
One-shotbash
Runs one prompt and exits with code 0 on success.
python main.py "List all Python files in the project"
flux "Refactor src/utils.py to add type hints"