Configuration

API Keys

Fliiq needs at least one LLM API key. Add them to ~/.fliiq/.env:

.env

# LLM providers (at least one required)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...

Priority order: Anthropic > OpenAI > Gemini. If your primary provider fails, Fliiq automatically falls back to the next available one. To change the default, see Provider Switching below.

Recommended Models

For best results with Anthropic (recommended provider):

Model	Best for	Notes
Claude Sonnet 5	Most tasks	Best balance of speed and capability. Recommended default.
Claude Opus 5	Heavy computation	Complex refactors, deep research, multi-step reasoning. Overkill for most use cases — Sonnet handles the vast majority of tasks well.

Fliiq works with any model your provider supports. Sonnet 5 is the sweet spot for daily use.

Provider Switching

When multiple API keys are set, Fliiq uses the default priority order (Anthropic > OpenAI > Gemini). Override this per-command with the --provider flag:

fliiq --provider openai               # REPL with OpenAI/GPT-4o
fliiq run "task" --provider gemini     # Single-shot with Gemini
fliiq tui --provider anthropic         # TUI with Claude

For a persistent default, set FLIIQ_PROVIDER in your .env:

.env

FLIIQ_PROVIDER=openai

Resolution order:

--provider flag (highest priority)
FLIIQ_PROVIDER environment variable
First API key found (Anthropic > OpenAI > Gemini)

See CLI Reference for the full list of commands that accept --provider.

Model Selection

Switch models per-command with --model (or -m):

fliiq run "build a Jira skill" --model opus-5       # Use Opus for complex tasks
fliiq run "check my inbox" --model sonnet-5         # Use Sonnet for daily tasks
fliiq run "task" --model gpt-5.6                    # Use OpenAI GPT-5.6

View all available aliases with:

fliiq models

Built-in Aliases

Default aliases shipped with fliiq init:

Anthropic	OpenAI	Gemini
`fable-5`	`gpt-5.6`	`gemini-3.1-pro`
`opus-5`	`gpt-5.6-terra`	`gemini-3.6-flash`
`sonnet-5`	`gpt-5.6-luna`	`gemini-3.5-flash-lite`
`haiku-4.5`

Custom Aliases

Aliases are defined in ~/.fliiq/models.yaml (created by fliiq init). Add your own for Ollama, Mistral, DeepSeek, or any other provider:

# ~/.fliiq/models.yaml
aliases:
  # ... default aliases above ...

  # Custom aliases — add yours here
  mistral-large: mistral-large-latest
  mistral-small: mistral-small-latest
  mistral-codestral: codestral-latest
  deepseek-v3: deepseek-chat
  deepseek-coder: deepseek-coder
  llama-3.2: llama3.2:latest
  qwen-2.5: qwen2.5:latest

Then use them like any built-in alias:

fliiq run "task" --model mistral-large --provider openai

Any string not found in aliases is passed through as-is to the provider API.

Persistent Model Override

Override the default model for a provider via environment variable in your .env:

.env

ANTHROPIC_MODEL=claude-opus-5
OPENAI_MODEL=gpt-5.6
GEMINI_MODEL=gemini-3.6-flash

Resolution order: --model flag (highest) > env var (ANTHROPIC_MODEL, etc.) > hardcoded default.

Output Limits and Truncation

Default max_tokens per response is 16384. Override it with FLIIQ_MAX_TOKENS in .env. Anthropic requests automatically use prompt-prefix caching — the stable system prompt and tool schemas are cached, and cache hits bill at roughly 10% of normal input token price. No configuration needed. For long-running Anthropic sessions approaching the context window limit, opt into server-side context compaction with FLIIQ_CONTEXT_COMPACTION=1. If a response is cut off by the output token limit or the agent hits its iteration limit, Fliiq now says so explicitly rather than silently returning a clipped or empty reply — truncated tool calls are discarded instead of executed, and iteration-limited runs get a final wrap-up summarizing what was done and what’s left.

Self-Hosted LLMs

Fliiq can connect to any OpenAI-compatible server — Ollama, vLLM, llama.cpp, LM Studio, LocalAI, or any other server that implements the OpenAI API. Set OPENAI_BASE_URL to point Fliiq at your local server:

.env

OPENAI_API_KEY=not-needed
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=llama3.2

OPENAI_API_KEY must still be set (most local servers ignore it — any non-empty value works).

Quick Start with Ollama

# 1. Install Ollama (https://ollama.com) and start it
ollama serve

# 2. Pull a model
ollama pull llama3.2

Add to ~/.fliiq/.env:

.env

OPENAI_API_KEY=not-needed
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=llama3.2

# 3. Run Fliiq with your local model
fliiq --provider openai

If you also have a cloud API key set, switch between local and cloud with --provider:

fliiq --provider openai      # Local Ollama
fliiq --provider anthropic   # Cloud Claude

Anthropic-Compatible Proxies

If you use a proxy that implements the Anthropic API, set ANTHROPIC_BASE_URL:

.env

ANTHROPIC_BASE_URL=https://your-proxy.example.com

Self-hosted models vary in capability. Fliiq’s agent loop works best with models that support tool/function calling. Most large models (Llama 3.2+, Mistral, Qwen) support it via the OpenAI-compatible API.

Integration Credentials

Optional — add these when you need the corresponding skills:

Google (OAuth)

.env

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret

Required for fliiq google auth — the OAuth flow that authorizes Fliiq to access Gmail, Google Calendar, Drive, Sheets, Docs, and Slides. See Google Integration for full setup. Used by: send_email, receive_emails, mark_email_read, archive_email, delete_email, google_calendar, google_drive, google_sheets, google_docs, google_slides

Gmail — Fliiq’s Bot Email

.env

FLIIQ_GMAIL_ADDRESS=my-fliiq@gmail.com
FLIIQ_GMAIL_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

Gives Fliiq its own email address as a channel. The app password is optional if you’ve authorized this account via OAuth instead.

Gmail — App Password (legacy)

.env

GMAIL_ADDRESS=you@gmail.com
GMAIL_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

Fallback for email skills when OAuth is not configured. Requires a Google App Password. We recommend OAuth instead — it’s more secure and unlocks Calendar access.

Twilio (SMS)

.env

TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1234567890

Get these from the Twilio Console. Used by: send_sms, receive_sms

.env

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_ALLOWED_CHAT_IDS=12345678,87654321

Create a bot via @BotFather on Telegram. TELEGRAM_ALLOWED_CHAT_IDS restricts which chats the bot responds to. Used by: send_telegram, send_telegram_audio, Telegram real-time listener (daemon)

Slack

.env

SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_ALLOWED_CHANNELS=C0123456789

Create an app at api.slack.com/apps with Socket Mode enabled. SLACK_APP_TOKEN and SLACK_BOT_TOKEN together activate the daemon’s real-time listener for DMs and @-mentions. SLACK_ALLOWED_CHANNELS is optional — see Slack channel guide for setup details. Used by: slack, Slack real-time listener (daemon)

MiniMax (Text-to-Speech)

.env

MINIMAX_API_KEY=...
MINIMAX_GROUP_ID=...

Get these from the MiniMax Platform. The Group ID is found in your account settings. Used by: text_to_speech

Web Search

.env

BRAVE_API_KEY=BSA...

Get a free key from Brave Search API. Used by: web_search

Spotify

.env

SPOTIFY_CLIENT_ID=...
SPOTIFY_CLIENT_SECRET=...
SPOTIFY_ACCESS_TOKEN=...

Create an app at the Spotify Developer Dashboard. Used by: spotify

Directory Structure

Global (`~/.fliiq/`)

Created by fliiq init. Used from any terminal.

Path	Purpose
`.env`	API keys and credentials
`user.yaml`	User profile — name, labeled email accounts (details)
`models.yaml`	Model aliases for `--model` flag (details)
`google_tokens.json`	OAuth tokens for authorized Google accounts (auto-managed)
`memory/`	Persistent memory files
`memory/MEMORY.md`	Curated memory (always loaded into prompt)
`audit/`	Audit trails from every agent run
`skills/`	User-generated skills (available globally)

Project (`.fliiq/`) — optional

Created by fliiq init --project. Overrides global for this project.

Path	Purpose
`SOUL.md`	Agent personality overrides
`playbooks/`	Custom domain playbooks
`mcp.json`	MCP server connections
`memory/`	Project-specific memory
`audit/`	Project-specific audit trails
`jobs/`	Scheduled job definitions (YAML)
`skills/`	Project-specific skills

Bundled (inside the package)

Ships with Fliiq. Cannot be modified directly.

Path	Purpose
`data/skills/core/`	33 bundled skills
`data/soul/SOUL.md`	Default agent personality
`playbooks/coding.md`	Default coding playbook

Config Resolution

When Fliiq looks for a resource (skills, SOUL.md, playbooks, memory):

Project .fliiq/ — checked first
Global ~/.fliiq/ — fallback
Bundled defaults — final fallback

This lets you customize per-project without affecting your global setup, and ensures sensible defaults when nothing is configured.

Getting Started

Guides

Skills

Daemon & Jobs

Channels

Configuration

API Keys

Recommended Models

Provider Switching

Model Selection

Built-in Aliases

Custom Aliases

Persistent Model Override

Output Limits and Truncation

Self-Hosted LLMs

Quick Start with Ollama

Anthropic-Compatible Proxies

Integration Credentials

Google (OAuth)

Gmail — Fliiq’s Bot Email

Gmail — App Password (legacy)

Twilio (SMS)

Telegram

Slack

MiniMax (Text-to-Speech)

Web Search

Spotify

Directory Structure

Global (`~/.fliiq/`)

Project (`.fliiq/`) — optional

Bundled (inside the package)

Config Resolution

​API Keys

​Recommended Models

​Provider Switching

​Model Selection

​Built-in Aliases

​Custom Aliases

​Persistent Model Override

​Output Limits and Truncation

​Self-Hosted LLMs

​Quick Start with Ollama

​Anthropic-Compatible Proxies

​Integration Credentials

​Google (OAuth)

​Gmail — Fliiq’s Bot Email

​Gmail — App Password (legacy)

​Twilio (SMS)

​Telegram

​Slack

​MiniMax (Text-to-Speech)

​Web Search

​Spotify

​Directory Structure

​Global (~/.fliiq/)

​Project (.fliiq/) — optional

​Bundled (inside the package)

​Config Resolution

API Keys

Recommended Models

Provider Switching

Model Selection

Built-in Aliases

Custom Aliases

Persistent Model Override

Output Limits and Truncation

Self-Hosted LLMs

Quick Start with Ollama

Anthropic-Compatible Proxies

Integration Credentials

Google (OAuth)

Gmail — Fliiq’s Bot Email

Gmail — App Password (legacy)

Twilio (SMS)

Telegram

Slack

MiniMax (Text-to-Speech)

Web Search

Spotify

Directory Structure

Global (`~/.fliiq/`)

Project (`.fliiq/`) — optional

Bundled (inside the package)

Config Resolution