> ## Documentation Index
> Fetch the complete documentation index at: https://safia.maximusolution.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart: Install SAFIA and Run Your Finance Bot
> Install SAFIA on your machine, run the setup wizard, and send your first message to your personal finance bot on Telegram — all in under five minutes.
Getting SAFIA running takes three commands. The installer handles Git, Python 3.12, uv, and all dependencies automatically, then registers a `safia` CLI so you can manage the bot from anywhere in your terminal. No external cache server is required — SAFIA uses an in-memory cache backed by SQLite. Follow the steps below to go from zero to a live Telegram bot.
## Prerequisites
Before you start, make sure you have:
* A **Telegram bot token** — create one for free by messaging [@BotFather](https://t.me/BotFather) on Telegram and running `/newbot`
* An **LLM API key** from [Lunos](https://lunosrouter.com), [Groq](https://console.groq.com), [OpenAI](https://platform.openai.com), or any OpenAI-compatible provider
* A machine running Linux, macOS, or Windows with internet access
SAFIA does not require any external cache server. Chat history, rate-limit counters, and market data caches live in an in-memory cache that is persisted to SQLite (`CACHE_DB_PATH`), so cached state survives bot restarts.
## Installation & Setup
Run the one-line installer for your operating system. It sets up all dependencies and registers the `safia` CLI command.
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/superXdev/SAFIA/main/install.sh | bash
```
The installer automatically handles Git, uv, Python 3.12, and all Python dependencies. No Docker or external cache server required.
On Windows, always launch PowerShell with **Run as administrator** before installing or starting SAFIA. The installer registers a Scheduled Task and writes to system locations, and the bot daemon needs the same elevation to start cleanly. Right-click the PowerShell icon and choose **Run as administrator**.
```powershell theme={null}
iex (irm https://raw.githubusercontent.com/superXdev/SAFIA/main/install.ps1)
```
The installer checks for Git, Python, and uv (installing uv automatically if missing). No external cache server is required.
Once complete, the `safia` command is available in any new terminal session.
The interactive setup wizard creates your `.env` configuration file. It walks you through each required setting one prompt at a time.
```bash theme={null}
safia setup
```
You will be asked for:
* Your **Telegram bot token**
* Your **LLM provider** (Lunos, Groq, OpenAI, or custom)
* Your **LLM API key**
* Database URL and persistent cache file path (defaults are pre-filled and work out of the box)
* Optional: a Groq API key for voice transcription (Whisper) if your LLM provider is not Groq
* Optional: a Firecrawl API key for web search and article fetching
Accept the default values for `DATABASE_URL` and `CACHE_DB_PATH` unless you have a specific reason to change them. SQLite (for both your data and the persisted cache) is the recommended starting point.
Launch the bot and admin dashboard as background daemons. On Linux this uses systemd, on macOS launchd, and on Windows Scheduled Tasks — so SAFIA restarts automatically after a reboot.
```bash theme={null}
safia start
```
Verify everything is running:
```bash theme={null}
safia status
```
To watch recent logs:
```bash theme={null}
safia logs
```
Open Telegram and find the bot you created with BotFather. Send the `/start` command to begin a new session, or send `/help` to see an overview of what SAFIA can do.
From here, just chat naturally. For example:
* *"I spent 45000 on lunch today"*
* *"Show me my expenses this week"*
* *"What's the current gold price?"*
SAFIA responds in whatever language you write in. The daily message limit is **1000 messages per user** by default — you can raise this with the `DAILY_MESSAGE_LIMIT` variable in your `.env`.
The admin dashboard provides usage metrics, a user registry, and tools for uploading knowledge base documents.
Open your browser and navigate to:
```text theme={null}
http://127.0.0.1:5454
```
The dashboard requires HTTP Basic Auth. Set `ADMIN_USERNAME` and `ADMIN_PASSWORD` in your `.env` file (or run `safia config` to edit them) before accessing the dashboard for the first time. If these are not set, the dashboard is accessible without a password — protect it before exposing the port.
## CLI Reference
The `safia` CLI manages every aspect of the bot's lifecycle.
| Command | Description |
| ----------------- | --------------------------------------------- |
| `safia setup` | Run the interactive setup wizard |
| `safia config` | View and edit configuration interactively |
| `safia start` | Start bot and admin dashboard daemons |
| `safia stop` | Stop both daemons |
| `safia restart` | Restart both daemons |
| `safia status` | Show current daemon status |
| `safia logs [N]` | Show recent logs (default: last 30 lines) |
| `safia update` | Pull latest changes, update deps, and restart |
| `safia test` | Run the test suite |
| `safia uninstall` | Remove SAFIA completely |
## Next Steps
Customise your LLM provider, database backend, rate limits, and more.
Upload knowledge base documents and monitor user activity.