> ## 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 Overview: Install and Quick Start Guide

> Learn how to install and use the safia CLI to set up, control daemons, and maintain your SAFIA Telegram bot instance from the command line.

The `safia` CLI is the single command you use to control every aspect of your SAFIA installation — from the first-time setup wizard to starting daemons, watching logs, and pulling updates. Once installed, the CLI wraps your bot and admin dashboard as background daemons that survive reboots, so you never have to manage processes manually.

## Installation

<Tabs>
  <Tab title="Linux / macOS">
    Run the one-line installer in your terminal. It automatically handles Git, Python 3.12, the `uv` package manager, all Python dependencies, and the `safia` command itself — no Docker required. SAFIA uses an in-memory cache backed by SQLite, so no separate cache server needs to be installed.

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/superXdev/SAFIA/main/install.sh | bash
    ```

    SAFIA is installed to `~/.safia/safia` and the `safia` binary is placed at `~/.local/bin/safia`. The daemon auto-starts on reboot via **systemd** (Linux) or **launchd** (macOS).
  </Tab>

  <Tab title="Windows (PowerShell)">
    <Warning>
      On Windows, always start PowerShell with **Run as administrator** before running the installer or any `safia` command (`safia setup`, `safia start`, `safia restart`, `safia update`, `safia uninstall`). Right-click the PowerShell icon in the Start menu and choose **Run as administrator**. Without elevation, registering the Scheduled Task and starting the daemon will fail.
    </Warning>

    Run the following command in the elevated PowerShell window:

    ```powershell theme={null}
    iex (irm https://raw.githubusercontent.com/superXdev/SAFIA/main/install.ps1)
    ```

    The installer checks for Git, Python, and `uv` (auto-installs `uv` if missing). The daemon is registered as a **Scheduled Task** for auto-start on reboot.

    <Note>
      SAFIA does not require any external cache server on any platform. Chat history, rate-limit counters, and market data caches are kept in an in-memory cache that is persisted to SQLite (`CACHE_DB_PATH`), so state survives bot restarts.
    </Note>
  </Tab>
</Tabs>

After the installer finishes, confirm the `safia` command is available:

```bash theme={null}
safia --help
```

<Note>
  If your shell reports `safia: command not found`, `~/.local/bin` is not in your `PATH`. Add it and reload your shell:

  ```bash theme={null}
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
  source ~/.bashrc
  ```

  Use `~/.zshrc` instead if you use Zsh.
</Note>

## All commands at a glance

| Command           | Description                                             |
| ----------------- | ------------------------------------------------------- |
| `safia setup`     | Run the interactive setup wizard — creates `.env`       |
| `safia config`    | View and edit configuration interactively               |
| `safia start`     | Start the bot and admin dashboard as background daemons |
| `safia stop`      | Stop both daemons                                       |
| `safia restart`   | Restart both daemons                                    |
| `safia status`    | Show running/stopped status of both daemons             |
| `safia logs [N]`  | Tail recent log output (default: 30 lines)              |
| `safia test`      | Run the test suite                                      |
| `safia update`    | Pull latest changes, update dependencies, and restart   |
| `safia uninstall` | Remove SAFIA completely from your system                |

## Getting help

Run `safia help` (or `safia --help`) at any time to print a concise command reference directly in your terminal:

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

## Common workflows

### Initial setup

Follow these steps the first time you install SAFIA:

<Steps>
  <Step title="Install SAFIA">
    Run the one-line installer for your platform (see [Installation](#installation) above). The installer clones the repository, installs Python and all dependencies, and registers the `safia` command.
  </Step>

  <Step title="Run the setup wizard">
    ```bash theme={null}
    safia setup
    ```

    The interactive wizard walks you through choosing an LLM provider, entering API keys, configuring the database and persistent cache file, and setting up the admin dashboard. It writes everything to a `.env` file when you confirm.
  </Step>

  <Step title="Start the daemons">
    ```bash theme={null}
    safia start
    ```

    This starts the Telegram bot and the admin dashboard (`http://127.0.0.1:5454`) as background daemons. Both are configured to restart automatically if they crash and to start on reboot.
  </Step>

  <Step title="Verify everything is running">
    ```bash theme={null}
    safia status
    ```

    You should see both the bot and the admin dashboard reported as running. Open Telegram, find your bot, and send `/start` to confirm it responds.
  </Step>
</Steps>

### Daily use

Once the bot is up and running, most of your interaction with the CLI is limited to a few commands:

```bash theme={null}
safia status          # Are the daemons running?
safia logs            # What happened recently? (last 30 lines)
safia logs 100        # Show last 100 lines
safia restart         # Apply a config change without a full redeploy
```

### Editing configuration

If you need to change an API key, switch LLM providers, or update the admin password after the initial setup:

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

The interactive configuration manager loads your current `.env`, lets you edit any section, and writes the updated file (creating a `.env.backup` automatically). Restart the bot to apply changes:

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

### Updating SAFIA

Pull the latest code, update Python dependencies, and restart in one step:

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

<Tip>
  Run `safia status` before and after updating to confirm both daemons come back online cleanly.
</Tip>