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 
safia setup
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. Redis URL — defaults to redis://localhost:6379/0
  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.
If Redis is not reachable at localhost:6379 when the wizard runs, it will warn you and pause. Start Redis before continuing or provide a different REDIS_URL.

​
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 
safia config
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:
Menu itemVariables affected
View configurationRead-only display of all current values
Telegram Bot TokenTELEGRAM_BOT_TOKEN
AI Provider & API KeyLLM_PROVIDER, LLM_API_KEY, LLM_BASE_URL
AI ModelLLM_MODEL
Groq Key (voice transcription)GROQ_API_KEY
Firecrawl Key (web search)FIRECRAWL_API_KEY
Database URLDATABASE_URL
Redis URLREDIS_URL
Admin DashboardADMIN_USERNAME, ADMIN_PASSWORD, FLASK_SECRET_KEY
Advanced settingsVISION_MODEL, REMINDER_ENABLED, REMINDER_TICK_SECONDS, rate limits
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: 
safia restart

​
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 
safia start
Platform behavior
PlatformDaemon systemAuto-start
Linuxsystemd user services (safia.service, safia-admin.service)Enabled on first start
macOSlaunchd agents (com.safia.bot, com.safia.admin)Enabled on first start
WindowsScheduled TasksEnabled on first start
Example output 
→ Daemon configured (auto-start on boot enabled).
✓ SAFIA started (bot + admin dashboard on http://127.0.0.1:5454).
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 
safia stop
Example output 
✓ SAFIA stopped.
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 
safia restart
Example output 
✓ SAFIA restarted.

​
safia status

Shows whether the bot and admin dashboard daemons are currently running. Syntax 
safia status
Example output (both running) 
✓ SAFIA is running (bot + admin dashboard on http://127.0.0.1:5454)
Example output (stopped) 
✗ SAFIA is not running.
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 
safia logs        # Show last 30 lines from each log
safia logs 100    # Show last 100 lines from each log
Parameters
ParameterDefaultDescription
N30Number of lines to show from each log file
Example output 
═══ Bot logs (~/.safia/logs/bot.log) ═══
2024-01-15 10:23:41 INFO  Bot started successfully
2024-01-15 10:23:45 INFO  Received message from user 123456789
...

═══ Admin logs (~/.safia/logs/admin.log) ═══
2024-01-15 10:23:42 INFO  Admin dashboard started on http://127.0.0.1:5454
...
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 
safia test
You can narrow down which tests run by passing filter options: 
safia test -k "expense"      # Run only tests matching a keyword
safia test --tb=short        # Use a shorter traceback format

​
safia update

Pulls the latest code from the main branch, updates Python dependencies, and restarts the daemons — all in one command. Syntax 
safia update
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 
→ Updating SAFIA...
✓ SAFIA updated and restarted.
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 
safia uninstall
The command lists exactly what will be deleted and asks you to type yes to confirm: 
This will permanently remove SAFIA from your system.
  • ~/.safia  (all code, config, data, logs)
  • ~/.local/bin/safia  (CLI command)

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.Redis data and any Docker containers you created are not touched by the uninstaller.