SAFIA CLI Overview: Install and Quick Start Guide

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

Linux / macOS
Windows (PowerShell)

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.

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

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.

Run the following command in the elevated PowerShell window:

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.

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.

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

safia --help

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

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Use ~/.zshrc instead if you use Zsh.

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:

safia help

Common workflows

Initial setup

Follow these steps the first time you install SAFIA:

Install SAFIA

Run the one-line installer for your platform (see Installation above). The installer clones the repository, installs Python and all dependencies, and registers the safia command.

Run the setup wizard

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.

Start the daemons

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.

Verify everything is running

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.

Daily use

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

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:

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:

safia restart

Updating SAFIA

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

safia update

Run safia status before and after updating to confirm both daemons come back online cleanly.

​Installation

​All commands at a glance

​Getting help

​Common workflows

​Initial setup

​Daily use

​Editing configuration

​Updating SAFIA

Installation

All commands at a glance

Getting help

Common workflows

Initial setup

Daily use

Editing configuration

Updating SAFIA