app/docs/code/cli.md

# The `fluksio` command

```sh
pip install fluksio
```

Installs the engine and the `fluksio` command. Python 3.10 or newer, Linux or
macOS.

There is a second, smaller distribution — `fluksio-worker` — for a machine that
should only *run nodes* for an engine elsewhere. It has none of the engine in
it. See [Remote workers](workers.md).

## `fluksio serve`

Runs the engine.

```sh
fluksio serve
```

On the first start it creates an admin account and prints its password **once**.
Nothing else has to be running: no database server, no message broker, no
Docker.

| Option | Default | What it does |
|---|---|---|
| `--data-dir PATH` | `~/.fluksio` (or `$FLUKSIO_HOME`) | where this installation keeps everything |
| `--host HOST` | `127.0.0.1` | what to bind |
| `--port PORT` | `8000` | what to listen on |
| `--log-level LEVEL` | `info` | uvicorn's log level |
| `--admin-email ADDR` | `admin@example.com` | the account created on first run |
| `--admin-password PW` | generated | set it instead of having one generated |
| `--enroll CODE` | — | pair with a portal as part of coming up |
| `--portal URL` | — | the portal `--enroll` redeems at |

`--enroll` with `--portal` is the one-command setup: it pairs before the engine
starts, so the connection is dialled as part of coming up rather than needing a
restart. It is skipped if the installation is already enrolled.

!!! warning "One process"

    `fluksio serve` holds the flow engine. A second one is a *second engine* —
    duplicated subscriptions, duplicated cron ticks, two webhooks answering the
    same path. Run one, and distribute work with
    [workers](workers.md) instead.

!!! note "`$HOME` on a cluster"

    A login node's home directory is often NFS, where SQLite's write-ahead log
    does not work — the database would be locked or corrupt. `fluksio serve`
    warns when it notices; point `--data-dir` at local disk.

### What it prints

```text
Created the admin account admin@example.com
  password: k3Qm-8vTpLdX
  Shown once. Change it from the dashboard.
Fluksio 0.1.0 — data in /home/you/.fluksio
  API      http://127.0.0.1:8000/api/v1
  No portal. Pair this installation with:
    fluksio enroll <code> --portal https://hub.example.com
```

An enrolled installation says which portal it is on instead, and notes that the
dashboard is served from there rather than here.

## `fluksio enroll`

Pairs an existing installation with a portal.

```sh
fluksio enroll ABCD-1234 --portal https://hub.fluksio.com
```

| Option | What it does |
|---|---|
| `--portal URL` | **required** — the portal the code was minted on |
| `--as EMAIL` | the local account a portal session arrives as |
| `--data-dir PATH` | which installation, if not the default |

Get the code from the portal under **Installations → Add installation**. It is
single-use and expires in fifteen minutes. `--as` matters when the installation
has several superusers — without it, enrolment refuses rather than guessing.

Afterwards, `fluksio serve` dials the portal as it comes up. See
[Accounts and the portal](../interface/portal.md).

## `fluksio worker`

Runs nodes for an engine elsewhere. Everything after `worker` belongs to the
agent's own parser — it is the same program `fluksio-worker` installs, so the
two are interchangeable:

```sh
fluksio worker --url wss://api.example.com/api/v1/workers/attach \
               --token "$FLUKSIO_WORKER_TOKEN" --labels gpu
```

See [Remote workers](workers.md).

## What lives in the data directory

```text
~/.fluksio/
├── fluksio.db          SQLite: users, runs, metrics, observability, agents
├── flows/              a git repository — one directory per flow
│   ├── house/
│   │   ├── flow.json           the published structure
│   │   ├── nodes/*.py          the published node code
│   │   ├── flow.draft.json     unpublished edits, if any
│   │   └── nodes.draft/*.py
│   ├── _lib/           shared node sources
│   ├── _dashboards/    dashboards, drafts and all
│   └── requirements.txt        what the Modules screen installs
├── artifacts/          content-addressed bytes, two levels deep
├── user-venv/          the interpreter your node code runs on
├── secrets.enc         encrypted credentials, deliberately outside flows/
├── alerts.json         alert channels and rules
├── panels.json         wall-panel pairings
├── oauth-key.pem       signs agent tokens
├── cloud.json          the portal enrolment, if there is one
├── secret_key          signs sessions and derives the secrets key
└── env                 optional settings file
```

Two things follow from this layout and are worth internalising:

**`flows/` is a real git repository.** `git log` is the history of every change
anyone made to any flow. A run records the commit it ran at, so `git show` on
that hash is literally the code that produced the number.

**Backing up the data directory backs up the installation.** Everything else is
rebuildable. Copy it while the engine is stopped, or use SQLite's online backup
for the database if it is not.

## Settings

Settings come from the environment, or from an `env` file in the data
directory. The ones you are most likely to touch:

| Variable | Default | What it does |
|---|---|---|
| `DATA_DIR` | `~/.fluksio` via the CLI | everything below it derives from this |
| `DATABASE_URL` | SQLite in the data dir | any SQLAlchemy URL |
| `REDIS_HOST` | unset | flow state in Redis instead of memory; survives a restart |
| `FRONTEND_HOST` | — | the address used in mails, OAuth metadata and panel links |
| `ENVIRONMENT` | `local` | `production` closes the interactive API schema |
| `MCP_ENABLED` | `false` | opens the [agent endpoint](agents.md) |
| `SECRET_KEY` | generated once | signs sessions, derives the secrets key |

The full list is in [Configuration](../reference/configuration.md).