Skip to main content
Every action you need to manage your SAFIA installation — from first-time configuration to day-to-day operations and eventual removal — is exposed through a single safia command. This page documents each subcommand in detail.

​
Setup commands

​
safia setup

Runs the interactive setup wizard. This is the first command you run after installation. It guides you through every required configuration option and writes the result to a .env file in your SAFIA installation directory. Syntax
What it does The wizard steps through the following sections in order:
  1. Language selection — choose between Bahasa Indonesia and English
  2. Telegram bot token — paste the token from @BotFather
  3. LLM provider and API key — pick Lunos, Groq, OpenAI, or a custom endpoint
  4. Model selection — the wizard fetches available models from the provider and lets you pick or type one
  5. Groq API key for Whisper — enables voice message transcription (optional if provider is not Groq)
  6. Firecrawl API key — enables web search and article fetching (optional)
  7. Database URL — defaults to SQLite; accepts PostgreSQL connection strings
  8. Cache file path — defaults to data/cache.db (SQLite-backed in-memory cache; no external service required)
  9. Admin dashboard — set credentials for the web UI at http://127.0.0.1:5454
When you confirm, the wizard writes .env. If a .env already exists, it creates a .env.backup first.
SAFIA does not use 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 state survives restarts.

​
safia config

Opens the interactive configuration manager for editing an existing .env. Use this when you want to change individual settings — an API key, the LLM model, admin credentials — without re-running the full setup wizard. Syntax
What it does Displays a menu of configuration sections. Select a section, make your changes, then choose Save & Exit to write the updated .env. A .env.backup is created automatically before every write. Available sections in the menu:
Sensitive values (tokens, keys, passwords) are masked in the View configuration display. They are stored in plain text in .env — protect that file accordingly.
After saving, restart the bot to apply changes:

​
Daemon management commands

​
safia start

Starts the Telegram bot and the admin dashboard as background daemons. On first run, it also registers the services for auto-start on reboot. Syntax
Platform behavior Example output
safia start requires a .env file. If none is found, the command exits with an error and prompts you to run safia setup first.

​
safia stop

Stops both the bot daemon and the admin dashboard daemon. Syntax
Example output
The services remain registered for auto-start on the next reboot — they are only paused, not removed. Use safia uninstall if you want to remove the services entirely.

​
safia restart

Stops and then starts both daemons. Use this after changing .env to apply the new configuration. Syntax
Example output

​
safia status

Shows whether the bot and admin dashboard daemons are currently running. Syntax
Example output (both running)
Example output (stopped)
On Linux, safia status delegates to systemctl --user status and prints the full systemd unit status, including recent log excerpts.

​
safia logs [N]

Tails recent log output from both the bot and admin dashboard log files. Syntax
Parameters Example output
Log files are stored at:
  • Bot: ~/.safia/logs/bot.log
  • Admin dashboard: ~/.safia/logs/admin.log

​
Maintenance commands

​
safia test

Runs the SAFIA test suite with verbose output. Syntax
You can narrow down which tests run by passing filter options:

​
safia update

Pulls the latest code from the main branch, updates Python dependencies, and restarts the daemons — all in one command. Syntax
What it does, step by step
1

Fetch and pull

Runs git fetch origin main and git pull --ff-only origin main to fast-forward to the latest release.
2

Sync dependencies

Runs uv sync to install any new or updated Python packages declared in pyproject.toml.
3

Restart daemons

Calls safia restart so the updated code is loaded immediately.
Example output
Run safia logs after updating to confirm the bot started cleanly and there are no import errors or missing environment variables.

​
safia uninstall

Completely removes SAFIA from your system. This is irreversible. Syntax
The command lists exactly what will be deleted and asks you to type yes to confirm:
What gets removed
  • All SAFIA code, configuration, database files, and logs under ~/.safia/
  • The safia CLI binary at ~/.local/bin/safia
  • All registered daemon services (systemd units, launchd plists, or Scheduled Tasks)
Your bot’s SQLite database and uploaded knowledge base files are stored inside ~/.safia/safia/data/ and will be permanently deleted. Back them up first if you need to preserve conversation history or documents.The persisted cache file (CACHE_DB_PATH) and any Docker containers you created are not touched by the uninstaller.