FlowScale AIOS CLI

Standalone command-line build of FlowScale AIOS. Shares ~/.flowscale state with the desktop app.

Install

Requires Node ≥ 24 — it uses the built-in node:sqlite (no native build step). On Node 22.5–23.3 node:sqlite exists only behind --experimental-sqlite, which the CLI's flagless import 'node:sqlite' can't opt into, so those versions crash on startup and aren't supported.

npm i -g @rupayan10/aios-cli

Then run aios with no arguments (in a terminal) for a guided menu, or any command directly.

First run

On a fresh machine, run:

aios setup            # guided: detect hardware → install ComfyUI → generate instances → start → ready
aios setup --yes      # unattended, with sensible defaults (CI / scripting)
aios setup --json     # same, machine-readable summary (implies non-interactive)

aios setup is idempotent — already-configured steps report skipped, so it's safe to re-run. Bare aios on a machine with no ComfyUI configured also offers to launch this guided setup.

Usage

aios setup                   # guided first-run; --yes for unattended, --comfy-path to point at an existing install

aios config show [--json]                        # view config (ComfyUI path, install type, provider keys — masked)
aios config comfyui-path <path>                  # point the CLI at a ComfyUI install
aios config provider-key <provider> [key] [--stdin] [--unset]  # set (or --unset) a cloud provider API key;
                                                 # --stdin or AIOS_<PROVIDER>_KEY keeps it out of shell history

aios gpu list | detect
aios comfy detect            # generate instance configs from detected GPUs
aios comfy status
aios comfy start [id]        # start one instance or all (detached; survives CLI exit)
aios comfy stop [id]
aios comfy restart <id>
aios comfy logs <id> [-n 200]

aios tools list
aios tools build <workflow.json> [--name <name>] [--instance auto|<id>] \
                                 [--inputs <keys>] [--outputs <keys>] [--json]
aios tools run <id> --input k=v [--input [email protected]] [--instance auto|<id>] [--start] [--json]
aios tools show <executionId>
aios tools deploy <id> [--model-version <v>] [--json]   # flip dev → production (desktop parity)
aios tools config <id> [--hide <key>] [--show <key>] [--json]  # input/output visibility (shared with desktop UI)

aios providers list [--json]                     # cloud providers + key status
aios providers call <name> <path> [--method <m>] [--body <json|@file>]  # authenticated provider API call

aios models scan --instance auto|<id> [--json]   # HTTP-scan a running instance for models
aios models list [--type <type>] [--json]

aios plugins list [--json]
aios plugins install <id> [--json]               # install from the FlowScale registry
aios plugins import <path|url> [--json]          # import from a local dir or GitHub URL
aios plugins install-deps <id> [--json]          # install the plugin's Python deps (torch + declared packages)
aios plugins start <id>
aios plugins stop <id>
aios plugins logs <id> [-n 200]

aios assets list [--tool <id>] [--json]          # completed outputs resolved to disk
aios assets show <executionId> [--json]
aios assets open <executionId>                   # open the first output in the OS viewer

aios modal setup                                 # install the Modal CLI + authenticate
aios modal status [--json]                       # install/auth/account/workspace state
aios modal disconnect [--yes]                    # remove ALL Modal credentials (~/.modal.toml)
aios modal account add <name> [--token-id <id> --token-secret <secret>] [--no-activate] [--json]
aios modal account list [--json]                 # list Modal accounts (profiles)
aios modal account use <name> [--json]           # switch the active account
aios modal account remove <name> [--yes] [--json]# remove one account (edits ~/.modal.toml)
aios modal account current [--json]              # show the active account
aios modal deploy <pluginId> [--gpu <tier>] [--name <name>] [--json]   # deploy an API-engine plugin
aios modal undeploy <pluginId> <deployIdOrName> [--json]               # remove a deployment
aios modal deployments [--plugin <id>] [--json]  # list Modal deployments
aios modal comfyui deploy [--gpu <tier>] [--name <name>] [--cloud] [--node <url>…] [--model <url>…] [--json]
                                                 # deploy ComfyUI to Modal; cloud-native (stock ComfyUI, no local install)
                                                 # when --cloud / --node / --model given or no local ComfyUI is configured
aios modal comfyui cloud [--gpu <tier>] [--name <name>] [--node <url>…] [--model <url>…] [--yes] [--json]
                                                 # guided cloud-native setup wizard (no local install)
aios modal comfyui list [--json]                 # list Modal ComfyUI instances
aios modal comfyui undeploy <id> [--json]        # tear a Modal ComfyUI instance down
aios modal comfyui resync <id> [--json]          # re-scan local ComfyUI and redeploy
aios modal comfyui add-node <repoUrl> [--instance <id>]                # bake a node into a Modal instance, or clone locally
aios modal comfyui download-model <url> --type <t> --filename <name> [--key <token>]  # download a model into the Modal volume (--key: auth token for the download)
aios tools build <workflow.json> --instance modal# build a tool against a deployed Modal ComfyUI
aios models scan --instance modal                # scan a deployed Modal ComfyUI for models
aios tools run <id> --instance modal             # run an API- OR ComfyUI-engine tool on Modal

aios --help

Interactive mode

Running aios with no arguments in a terminal opens a guided menu: pick a command group (gpu, tools, comfy, models, plugins, assets), then a subcommand, then its primary argument — resolved from live data where possible (e.g. a tool/instance/execution picker). The chosen command is then dispatched exactly as if you had typed it.

Interactive mode is purely a convenience layer — every command stays fully scriptable with flags and --json. The menu is skipped (and the command runs normally) whenever:

• output is not a TTY (piped, redirected, or running in CI),
• --json is passed, or
• an explicit command is given (e.g. aios tools list).

So aios alone is interactive, while aios tools list, aios gpu list --json, and aios ... | cat all behave non-interactively and unchanged.

Building a tool

aios tools build <workflow.json> analyzes a ComfyUI workflow (API or graph format) and saves it as a dev-status ComfyUI tool with a sha256 workflow hash and the full input/output schema. Pass --instance auto|<id> to resolve custom-node widget parameter names via that running instance's /object_info. Use --inputs/--outputs (comma-separated nodeId__paramName keys) to keep only a subset of fields — the default persists every analyzed field. The new tool is immediately runnable via aios tools run <id>.

Models

aios models scan requires a running ComfyUI instance — it queries that instance's /models/{folder} HTTP endpoints (not the disk), so file sizes are unavailable (null). Each scan replaces the previously scanned models for that port; aios models list reads the persisted rows (optionally filtered by --type).

Plugins (API-engine tools)

aios plugins install <id> (registry) and aios plugins import <path|url> (local dir or GitHub URL) register an api-engine tool backed by a local HuggingFace inference plugin. Install its Python dependencies once with aios plugins install-deps <id> (torch + the packages the manifest declares). Run it with aios tools run <toolId> [--start], where --start launches the plugin's inference server first. Manage servers directly with aios plugins start|stop|logs <id>.

Assets

aios assets list shows the outputs of completed executions resolved to absolute disk paths under ~/.flowscale/aios-outputs/. aios assets show <executionId> lists a single execution's outputs, and aios assets open <executionId> opens the first resolvable output file in the OS default viewer (start on Windows, open on macOS, xdg-open on Linux).

ComfyUI tool inputs are keyed <nodeId>__<paramName> (e.g. --input 6__text="a cat"), and --input <key>=@path/to/image.png uploads a local image.

API-engine (plugin) tool inputs are keyed api__<paramName> instead (e.g. --input api__prompt="a cat"), distinct from ComfyUI tools' <nodeId>__<paramName>.

Plugin inference servers (plugins start/stop) are fully supported on macOS/Linux; on Windows, server start works but stop/stale-port cleanup is best-effort in v1.

Modal (cloud GPU)

Modal is a cloud-GPU provider. The CLI can install/authenticate Modal, deploy API-engine tool plugins to it, and run those tools on the cloud GPU:

aios modal setup                 # pip-installs the modal package if missing, then hands off
                                 # to Modal's interactive `modal setup` (opens your browser)
aios modal status                # show install / auth / account / workspace state
aios modal status --json         # machine-readable: { "installed": …, "authenticated": …, "account": …, "workspace": … }
aios modal disconnect            # remove ALL Modal credentials (~/.modal.toml; confirm prompt, --yes to skip)

aios modal account list          # list Modal accounts (profiles) with the active one marked
aios modal account add work --token-id <id> --token-secret <secret>   # add a named account non-interactively
aios modal account add work      # or interactively (opens your browser via `modal token new`)
aios modal account use work      # switch the active account
aios modal account current       # print the active account
aios modal account remove work   # remove one account (edits ~/.modal.toml; --yes to skip confirm)

aios modal deploy <pluginId>     # deploy an API-engine plugin (takes several minutes)
aios modal deploy <pluginId> --gpu A100-80GB --name big    # pick a GPU tier + name the deployment
aios modal undeploy <pluginId> <deployIdOrName>            # tear a deployment down
aios modal deployments [--plugin <id>] [--json]            # list deployments

aios tools run <toolId> --instance modal                   # run the tool on its Modal deployment

aios modal comfyui deploy --gpu A10 --name default         # deploy a ComfyUI instance to Modal (~10 min)
aios modal comfyui list [--json]                           # list Modal ComfyUI instances + virtual ports
aios modal comfyui resync <id>                             # re-scan local ComfyUI + redeploy
aios modal comfyui add-node <repoUrl> --instance <id>      # add a custom node locally, then resync
aios modal comfyui download-model <url> --type checkpoint --filename model.safetensors
aios modal comfyui undeploy <id>                           # tear a Modal ComfyUI instance down
aios tools run <toolId> --instance modal                   # ALSO runs a ComfyUI tool on Modal

Cloud-native ComfyUI (no local install)

You do not need a local ComfyUI to run one on Modal. Deploy stock ComfyUI straight to the cloud — optionally baking in custom nodes (by repo URL) and preloading models (by URL):

aios modal comfyui deploy --cloud                          # stock ComfyUI on Modal, nothing installed locally
aios modal comfyui deploy --cloud \
  --node https://github.com/city96/ComfyUI-GGUF \          # bake custom nodes in (repeatable)
  --model checkpoint:https://.../flux.safetensors          # preload models as [type:]url (repeatable);
                                                           # type ∈ checkpoint|lora|vae|controlnet|upscaler|other (default other)
aios modal comfyui cloud                                   # guided wizard (prompts for GPU/name/nodes/models)
aios modal comfyui cloud --yes --gpu A10 --node <url>      # same, unattended (flags + defaults)

deploy automatically goes cloud-native when --cloud, any --node/--model, or no local ComfyUI is configured; otherwise it scans your local install and mirrors it (the original behavior). Once an instance is deployed you can drive the whole workflow against it — its virtual port resolves to the Modal URL through the unchanged run/build/scan paths:

aios tools build workflow.json --instance modal            # analyze widgets via the Modal /object_info
aios models scan --instance modal                          # list the models available on the Modal instance
aios tools run <toolId> --instance modal                   # run the tool on Modal
aios modal comfyui add-node <repoUrl> --instance <cloudId> # bake a node into a deployed instance + redeploy

Modal needs Python 3 and the modal package — aios modal setup installs the package via pip install --user modal and then runs Modal's own interactive auth, which requires a terminal. On a non-TTY (CI/piped) it exits with guidance to add an account non-interactively instead: aios modal account add <name> --token-id <id> --token-secret <secret>. If a HuggingFace key is configured (aios config provider-key huggingface …), setup can optionally sync it to a Modal huggingface-secret.

aios modal status never errors when Modal isn't installed — it just reports installed: false.

Multiple accounts. Modal supports several named accounts (Modal calls them profiles), each with its own token, stored in ~/.modal.toml. aios modal account add/list/use/remove/current manage them, and the active account is used for every Modal operation (deploy, ComfyUI, tools run --instance modal). aios modal status shows the active account. aios modal account add takes --token-id/--token-secret for non-interactive use, or falls back to Modal's browser-based modal token new; aios modal account remove deletes just one account (strips its section from ~/.modal.toml), whereas aios modal disconnect removes them all.

Deploying plugins. Only API-engine plugins that ship a modal_app.py in their plugin directory (~/.flowscale/tool-plugins/<id>/) are Modal-deployable; aios modal deploy rejects plugins without one. The GPU tier defaults to the plugin manifest's cloud.modal.defaultGpu (or A10); valid tiers are T4, L4, A10, L40S, A100-40GB, A100-80GB, RTX-PRO-6000, H100, H200, B200. Any Modal secrets the plugin manifest declares in cloud.modal.requiredSecrets (e.g. a gated HuggingFace model) must already exist. Deployment state is persisted in ~/.flowscale/aios/modal-deployments.json, and aios tools run <id> --instance modal round-robins across a plugin's deployed instances.

ComfyUI on Modal. aios modal comfyui deploy scans your local ComfyUI (custom nodes + models) and deploys a shared ComfyUI instance to Modal — so you need a local ComfyUI configured (aios config comfyui-path … or aios comfy install). Each deployed instance is assigned a virtual port (50001–50999); aios tools run <toolId> --instance modal resolves that virtual port to the instance's Modal URL and runs the ComfyUI tool there via the normal upload/queue/poll path (round-robined across deployed instances). State lives in ~/.flowscale/aios/modal-comfyui.json. add-node clones a custom node into local ComfyUI (and, with --instance <id>, resyncs that instance); download-model pushes a model into the Modal volume (pass --key <token> for a gated or private download URL); resync re-scans + redeploys. A real deploy takes ~10 minutes. With nothing deployed, --instance modal for a ComfyUI tool errors with Deploy one: aios modal comfyui deploy.

License

AGPL-3.0-only