> ## 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.

# safia CLI Commands: Full Subcommand Reference Guide

> Detailed reference for every safia CLI command — syntax, behavior, options, and example output for setup, daemon management, and maintenance.

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**

```bash theme={null}
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. **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.

<Note>
  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.
</Note>

***

### `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**

```bash theme={null}
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 item                      | Variables affected                                                       |
| ------------------------------ | ------------------------------------------------------------------------ |
| View configuration             | Read-only display of all current values                                  |
| Telegram Bot Token             | `TELEGRAM_BOT_TOKEN`                                                     |
| AI Provider & API Key          | `LLM_PROVIDER`, `LLM_API_KEY`, `LLM_BASE_URL`                            |
| AI Model                       | `LLM_MODEL`                                                              |
| Groq Key (voice transcription) | `GROQ_API_KEY`                                                           |
| Firecrawl Key (web search)     | `FIRECRAWL_API_KEY`                                                      |
| Database URL                   | `DATABASE_URL`                                                           |
| Cache file path                | `CACHE_DB_PATH`                                                          |
| Admin Dashboard                | `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `FLASK_SECRET_KEY`                   |
| Advanced settings              | `VISION_MODEL`, `REMINDER_ENABLED`, `REMINDER_TICK_SECONDS`, rate limits |

<Warning>
  Sensitive values (tokens, keys, passwords) are masked in the **View configuration** display. They are stored in plain text in `.env` — protect that file accordingly.
</Warning>

After saving, restart the bot to apply changes:

```bash theme={null}
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**

```bash theme={null}
safia start
```

**Platform behavior**

| Platform | Daemon system                                                  | Auto-start             |
| -------- | -------------------------------------------------------------- | ---------------------- |
| Linux    | systemd user services (`safia.service`, `safia-admin.service`) | Enabled on first start |
| macOS    | launchd agents (`com.safia.bot`, `com.safia.admin`)            | Enabled on first start |
| Windows  | Scheduled Tasks                                                | Enabled on first start |

**Example output**

```text theme={null}
→ Daemon configured (auto-start on boot enabled).
✓ SAFIA started (bot + admin dashboard on http://127.0.0.1:5454).
```

<Note>
  `safia start` requires a `.env` file. If none is found, the command exits with an error and prompts you to run `safia setup` first.
</Note>

***

### `safia stop`

Stops both the bot daemon and the admin dashboard daemon.

**Syntax**

```bash theme={null}
safia stop
```

**Example output**

```text theme={null}
✓ 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**

```bash theme={null}
safia restart
```

**Example output**

```text theme={null}
✓ SAFIA restarted.
```

***

### `safia status`

Shows whether the bot and admin dashboard daemons are currently running.

**Syntax**

```bash theme={null}
safia status
```

**Example output (both running)**

```text theme={null}
✓ SAFIA is running (bot + admin dashboard on http://127.0.0.1:5454)
```

**Example output (stopped)**

```text theme={null}
✗ 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**

```bash theme={null}
safia logs        # Show last 30 lines from each log
safia logs 100    # Show last 100 lines from each log
```

**Parameters**

| Parameter | Default | Description                                |
| --------- | ------- | ------------------------------------------ |
| `N`       | `30`    | Number of lines to show from each log file |

**Example output**

```text theme={null}
═══ 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**

```bash theme={null}
safia test
```

You can narrow down which tests run by passing filter options:

```bash theme={null}
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**

```bash theme={null}
safia update
```

**What it does, step by step**

<Steps>
  <Step title="Fetch and pull">
    Runs `git fetch origin main` and `git pull --ff-only origin main` to fast-forward to the latest release.
  </Step>

  <Step title="Sync dependencies">
    Runs `uv sync` to install any new or updated Python packages declared in `pyproject.toml`.
  </Step>

  <Step title="Restart daemons">
    Calls `safia restart` so the updated code is loaded immediately.
  </Step>
</Steps>

**Example output**

```text theme={null}
→ Updating SAFIA...
✓ SAFIA updated and restarted.
```

<Tip>
  Run `safia logs` after updating to confirm the bot started cleanly and there are no import errors or missing environment variables.
</Tip>

***

### `safia uninstall`

Completely removes SAFIA from your system. This is irreversible.

**Syntax**

```bash theme={null}
safia uninstall
```

The command lists exactly what will be deleted and asks you to type `yes` to confirm:

```text theme={null}
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)

<Warning>
  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.
</Warning>