Fantastic CLI

Install, activate and operate a Fantastic media appliance — from one command.

$ npm i -g @wasmsoft/fantastic
$ fantastic

███████╗ █████╗ ███╗   ██╗████████╗ █████╗ ███████╗████████╗██╗ ██████╗
██╔════╝██╔══██╗████╗  ██║╚══██╔══╝██╔══██╗██╔════╝╚══██╔══╝██║██╔════╝
█████╗  ███████║██╔██╗ ██║   ██║   ███████║███████╗   ██║   ██║██║
██╔══╝  ██╔══██║██║╚██╗██║   ██║   ██╔══██║╚════██║   ██║   ██║██║
██║     ██║  ██║██║ ╚████║   ██║   ██║  ██║███████║   ██║   ██║╚██████╗
╚═╝     ╚═╝  ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝ ╚═════╝

Fantastic Media   Your rest house's own cinema — served from this machine, over your own network.
Welcome.   appliance · 1.4.0 · C:\Fantastic

Start typing — matching commands appear below.  ↑↓ to choose, Enter to fill it in.
Press / for the full list.  Leave with exit.

fantastic ›

What this is

A Fantastic appliance is a small machine in a rest house that serves films and live TV over the local network. This CLI is the only tool a technician needs to put one into service and keep it there: it installs the system, activates its licence, starts and stops it, reads its logs, diagnoses it, and updates it.

It answers questions about processes, ports, files and its own state. It never answers questions about content — that is the appliance's own HTTP API, and the boundary is deliberate.

Requirements

A JavaScript runtime, version 20 or newer. Nothing else.

winget install OpenJS.NodeJS.LTS
node -v
npm i -g @wasmsoft/fantastic

Run the install and update commands from an administrator terminal.

Ubuntu ships Node 18, which is below the minimum:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node -v

sudo npm i -g @wasmsoft/fantastic   # sudo: /usr/lib/node_modules belongs to root

The interactive shell

Running fantastic with no arguments inside a terminal opens a shell, so a technician runs one command after another without retyping the program name. Start typing, and matching commands appear beneath the prompt — each with what it does:

fantastic › st
    start             Start the services in order in the background and hand the terminal back
    status            Show each service: running or stopped, with its port, PID and uptime
    stop              Stop the services in reverse order and verify no orphans are left
    stream cancel     Cancel a transcode job and free its slot
    stream encoders   Show which encoder the core selected: hardware acceleration or software
    stream queue      Show the transcode queue: running, queued and failed jobs

Matching runs across whole command paths, not just first words, so li reaches library scan as readily as list, and the arrow keys choose between them:

fantastic › up
  › update          Update the appliance to the newest bundle, with automatic rollback
    backup          Write one dated archive of the database, settings, theme and owner assets
    self-update     Update this CLI tool itself from npm — not the appliance's services
    setup           Prepare an unconfigured system: dependencies, migrations, then start it

fantastic › li
    library drives    Show every drive a section points at: present or missing, with free space
    library relink    Reconnect sections whose drive letter changed, by volume identity
  › library scan      Scan a section and follow the progress
    library sections  List the library's sections with their paths
    library status    Show index counters and when the library was last scanned
    list              List the Fantastic products installed on this machine

The condition for opening the shell is deliberately threefold: no arguments, a terminal for input, and a terminal for output. In a script or a CI job the same bare command prints help and exits rather than waiting for a person who is not there.

Everyday commands

| Command | What it does | |---|---| | fantastic install estraha | Fetch the bundle, verify it, extract, migrate, seed and start | | fantastic activate <code> | Activate this appliance with a licence code | | fantastic status | Every service: running or stopped, with port, PID and uptime | | fantastic start · stop · restart | Control the services in order — and in reverse to stop | | fantastic logs core -n 50 | Show service logs, or follow them live | | fantastic doctor | Full diagnosis, offline, writing nothing | | fantastic update | Signed update of the appliance, with automatic rollback | | fantastic rollback | Go back to a previous published version — from a list, or by name | | fantastic self-update | Update this CLI from npm — not the appliance | | fantastic backup · restore | One dated archive of database, settings, theme and assets | | fantastic uninstall estraha | Remove the appliance, keeping customer data |

Grouped topics carry the rest: library (sections, drives, scanning, relinking), stream (queue, sessions, encoders), live (channels, source checks), iptv, db, owner and config.

Status

status answers the question a technician actually has on arrival — is it up, on which ports, and where does the owner point their browser:

fantastic › status

  ┌────────────────────────────────────────┬───────────┬──────┬─────┬────────┐
  │ Service                                │ State     │ Port │ PID │ Uptime │
  ├────────────────────────────────────────┼───────────┼──────┼─────┼────────┤
  │ Live service (started outside the CLI) │ * running │ 8081 │  -  │   -    │
  │ Core                                   │ * stopped │   80 │  -  │   -    │
  └────────────────────────────────────────┴───────────┴──────┴─────┴────────┘

  Portal     http://localhost/
  Login      http://localhost/login
  Dashboard  http://localhost/admin
  Network    http://192.168.1.3/

  Licence  -

profile: appliance  ·  database: C:\Fantastic\data\fantastic.db (992.0 KB)

Doctor

doctor is the tool for a machine that is misbehaving. It checks the environment, ports, media tooling, data and the integrity of what is installed — then states every problem with the command that fixes it:

fantastic › doctor

Environment
 ✔ Node runtime                       v22.15.0
 ✔ Profile                            appliance
 ✔ Data directory writable            writable
 ! PATH isolation                     bin\ is not on this process's PATH
   → Add C:\Fantastic\bin to the machine PATH, or open a new terminal.
 ✔ The `fantastic` command            resolves to the global package

Ports
 ✔ 8081  Live service                 in use by this service
 ✔ 80    Core                         free

Media tooling
 ✔ ffmpeg                             N-92722-gf22fcd4483
 ✔ ffprobe                            2023-02-13-git-2296078397

Data
 ✔ Database file                      992 KB
 ✔ DATA_DIR agreement (core ↔ live)   identical
 ✖ Core service                       not responding
   → Start it: fantastic start   ·   then check: fantastic logs core -n 50
 ? Owner account                      core unreachable

Integrity
 ✔ Restart loop                       none
 ✔ Installed components               4 match · signed by WasmSoft

1 blocking issue.  1 warning.  1 could not be determined.  doctor never writes; nothing was changed.

Three outcomes are distinguished on purpose — a failure (✖), a warning (!), and could not be determined (?). A check that could not run is never reported as a check that passed.

Updates

An update downloads the bundle, verifies its checksum against a manifest the centre signed, swaps the trees aside, migrates the database and starts the services. Any failure after the swap rolls the previous trees back, so a machine that was working is still working.

$ fantastic update --help

Update the appliance to the newest bundle, with automatic rollback — not this CLI
(that is `self-update`)

USAGE
  $ fantastic update [--profile dev|appliance] [--json] [--product <value>]
    [--check] [-y] [--channel stable|beta]
    [--code <value>]

FLAGS
  -y, --yes              Skip the confirmation prompt.
      --channel=<option> [default: stable] Release channel.  <options: stable|beta>
      --check            Report only; install nothing.
      --code=<value>     Activation code. Read from this machine's registry when omitted.
      --json             Emit machine-readable output instead of a rendered table.

EXAMPLES
  $ fantastic update --check
  $ fantastic update --yes

Since 1.9.0 the download is the update file whenever the centre has one covering the installed version: only the files that changed, usually a few megabytes, assembled with the installed tree and checked against the same signed digests as the full bundle. Anything that does not fit falls back to the full bundle in the same run. --component is retired: the whole system keeps one version.

Going back to a previous version

When a release turns out to have a problem, an appliance can return to any version the centre still publishes — until the fix is out, when update brings it forward again.

$ fantastic rollback

installed: 0.30.4
can go back to:
    1. 0.30.3     132 MB · published 2026-09-11
    2. 0.30.2     132 MB · published 2026-09-11

? Go back to which? Type its number or version; Enter alone cancels: 1

rollback runs exactly what update runs — download, verify, swap the trees aside, migrate, start, undo on failure — only toward an older version you chose. Three things to know:

• The centre decides the list. Only published bundles appear. A version withdrawn in the central dashboard cannot be gone back to, so withdrawing a broken release is what protects every appliance from it.
• The database is not rolled back. The older core runs on the newer schema and applies nothing; what was written since stays. A backup is taken first by default (--no-backup skips it — a backup needs the core running, and the broken core is often the reason you are here).
• Withdraw the bad version afterwards, or the next update and the pre-boot check will offer it again.

$ fantastic rollback --list                 # show the versions, change nothing
$ fantastic rollback --to 0.30.3 --yes      # no questions, for a script or a support call

Installing where there is no internet

Three files on a memory stick, three steps:

node-v22.x-x64.msi                                                # 1 — the runtime
npm i -g .\wasmsoft-fantastic-1.4.0.tgz                           # 2 — this CLI, from the file
fantastic install estraha --from .\Fantastic-x.y.z-win-x64.zip    # 3 — the appliance, from disk

A .tgz is attached to every release.

Platforms

One package serves both, and infers its platform rather than asking.

| | Windows | Linux | |---|---|---| | Architecture | x64 | x64 — glibc 2.28+ (musl is out of scope) | | Install root | C:\Fantastic | /opt/fantastic | | Return after power loss | Scheduled task as SYSTEM | systemd unit as root | | Privilege needed | Administrator | root (sudo) |

The install, update and uninstall commands are identical on both.

How it is built

| | | |---|---| | Language | TypeScript, strict, ESM throughout | | Framework | oclif for commands, flags and help | | Tests | Vitest — 400 across 32 files | | Supervisor | Ships separately from the CLI, with five dependencies rather than 143 | | Integrity | Ed25519 verification of bundle manifests against a compiled-in public key | | Rollback | Trees are swapped aside, never overwritten, until the services answer | | Registry | Atomic writes; a lost or half-written index rebuilds from disk instead of failing | | Readiness | Services are probed until they answer, with a timeout that fails cleanly |

A few decisions worth naming, because they are unusual:

• Nothing printed is written in Arabic. The Windows console applies no bidirectional reordering, so Arabic is drawn reversed and unreadable. A test enforces this over every shipped file and over the package manifest. Source comments stay bilingual — they are read in an editor, never printed.
• The installed-products index is a helper, not a source of truth. The bundle manifest on disk is the truth; a missing, truncated or newer-schema index rebuilds rather than blocks.
• The smoke boot is mandatory when a bundle is built. A bundle that never started is marked unverified in its manifest, and the installer refuses it.
• doctor never writes. Diagnosis that changes the thing being diagnosed is not diagnosis.

What it holds, and what it does not

The CLI holds no secret. What it carries is a release public key, compiled into the program, which doctor uses to check that a bundle manifest was signed by Fantastic. A public key is not a secret: this package is public, and anything secret inside it would be a published secret.

One thing it does hold, stated plainly: the activation code, in a file readable only by the machine's administrators. It is kept because checking for a newer bundle needs it before the core — which holds the licence — has started. Nothing else: no database credentials, no signing key, no licence material.

Licence validity is decided by the appliance's core, not by this CLI, and an update offer is verified by the core against the centre's signature before a download link ever reaches here.

Development

npm install
npm run build
npm run lint
npm run typecheck
npm test
npm link        # try the command globally, from source

Publishing runs on a v* tag: build → typecheck → tests → publish with provenance → attach the .tgz to the release.

Licence

Proprietary. © WasmSoft. Published to npm so licensed operators can install and update their appliances; it confers no right to use the Fantastic software itself.