@flux-finance/cli

Install and manage FluxFinance — a personal finance AI agent with Telegram bot and web UI.

Quick Start

npx @flux-finance/cli@latest

This launches an interactive setup wizard that guides you through everything.

Prerequisites

• Docker Desktop installed and running
• Node.js 18+

Setup Wizard

The wizard walks you through:

1. Docker check — verifies Docker is installed and running
2. Claude authentication — choose OAuth token or API key (see below)
3. Telegram bot creation — QR code + step-by-step instructions for @BotFather
4. Telegram user ID — QR code + instructions for @raw_data_bot
5. Configuration — Claude model selection and port
6. Install & start — pulls the Docker image and starts FluxFinance

Authentication Flow

The wizard and refresh-token command share the same token acquisition flow via acquireClaudeToken().

1. Entry Points

flowchart TD
    A["npx @flux-finance/cli<br/>(first run, no config)"] --> B[runWizard]
    C["npx @flux-finance/cli refresh-token"] --> D{Config exists?}
    D -- No --> E[EXIT 1: Run setup first]
    D -- Yes --> F[acquireClaudeToken]
    B --> F
    F --> G[Save token + start/restart container]

2. Token Acquisition (acquireClaudeToken)

flowchart TD
    A{Which auth method?} -- OAuth token<br/>recommended --> B{Claude CLI installed?}
    A -- API key<br/>never expires --> C[Prompt: paste API key<br/>sk-ant-api...]
    A -- Cancel --> D[Return null]

    B -- Yes --> E["Run: claude setup-token<br/>Parse stdout /sk-ant-oat.../"]
    B -- No --> F[Prompt: paste OAuth token<br/>sk-ant-oat...]

    E -- Token captured --> G[Return token]
    E -- Failed --> F
    F --> G
    C --> G

3. Inside Docker Container

flowchart TD
    A[".env: CLAUDE_AUTH_TOKEN"] --> B{Token prefix?}
    B -- "sk-ant-oat" --> C["Set CLAUDE_CODE_OAUTH_TOKEN"]
    B -- "sk-ant-api" --> D["Set ANTHROPIC_API_KEY"]
    C --> E[Claude Agent SDK]
    D --> E

    E -- Auth error --> F{Admin configured?}
    F -- Yes --> G["Notify admin via Telegram<br/>(throttled: 1x per hour)"]
    F -- No --> H["Reply to user:<br/>'temporarily unavailable'"]
    G --> H

Token Types

Commands

Configuration

All configuration is stored in ~/.flux-finance/:

~/.flux-finance/
├── .env                 # Credentials and settings
└── data/                # Application data (persisted across updates)
    ├── sqlite/          # Database
    ├── zvec/            # Vector embeddings
    └── backups/         # Backup archives

Environment Variables

Updating

npx @flux-finance/cli update

This pulls the latest Docker image and restarts the container. Your data is preserved.

Uninstalling

npx @flux-finance/cli stop
npx @flux-finance/cli reset

To also remove your data:

rm -rf ~/.flux-finance

License

MIT