CLI and TUI¶
CLI and TUI¶
dashboard/apps/cli builds one self-contained Node.js executable named
magicstick. It provides human-readable tables by default and JSON with
--json. Read commands cover the appliance overview, services, instances,
models and model discovery, settings, users, API keys, Kubernetes access, and
system status. Explicit mutation commands cover module lifecycle, arbitrary
catalog-backed instance payloads, model estimation and lifecycle, settings,
the complete local-user lifecycle, named API keys, and Kubernetes access and
kubeconfig generation.
The interactive magicstick tui command exposes the same role-filtered areas
as the React application and refreshes the shared snapshot automatically. It is
also a lifecycle client: operators can enable or disable catalog services,
create and remove application instances, show service and instance credentials
on request, create or remove local and external models, and start, stop or
restart them; administrators can change instance sharing, perform the
local-user lifecycle, create and revoke named API keys, and assign or revoke
SSO-backed Kubernetes access. The TUI calls the same authenticated API client
as the explicit CLI commands, preserves API authorization checks, confirms
destructive actions, masks passwords, and shows API-key secrets only once.
Token-free kubeconfigs can be copied with the terminal's OSC 52 clipboard
protocol. The create-instance form offers the same values as the browser form
and both send the same request; the complete JSON-payload CLI command remains
available for scripts. Editing a model's settings and reading model logs remain
in the browser.
The screen is laid out like the browser dashboard and is designed for a
terminal 120 columns wide. Below the banner, one line shows the connection and
the signed-in user. The page list on the left has the same pages as the browser
(Overview, Models, Services, API Access, Mesh, Kubernetes Access and System,
with the System sections as a button row). Pages consist of the same panels,
status badges and [ buttons ]. Mesh, Computer power, model editing and logs,
and the settings that the TUI cannot change point to the browser dashboard.
A cursor marks one element at a time. The arrow keys (or h/j/k/l) move
it to the nearest element in that direction, Tab and Shift+Tab walk through all
elements in reading order, and Enter or Space uses the element. In the page
list, Up and Down switch pages and Right enters the page; Left returns to the
list. Page Up, Page Down, Home and End scroll long pages, and the number keys
open a page directly. The bottom line is a hotkey bar: it names what Enter does
on the current element and lists the shortcuts of the current page, such as
a to add a model, n for a new instance, f to change the Services filter or s to change the
System section, together with r (reload), x (switch user or sign out), ?
(help) and q (quit).
Terminals that report mouse events, such as common SSH clients, also accept clicks on every element and hotkey-bar entry, and the wheel scrolls the page. Hold Shift to select text with the terminal while the TUI is open.
A mouse plugged into the appliance works on the attached monitor too, without
a graphical desktop. The Linux console itself reports no mouse, so the host's
console launcher runs the TUI behind a small helper that reads the kernel's
combined mouse device (/dev/input/mice) and sends the TUI the same reports a
terminal would; the TUI draws the pointer as a solid block. This needs both the
updated host role and the updated CLI image; with only one of them, or without
a mouse, the monitor is operated with the keyboard exactly as before. Set
dashboard_console_mouse_enabled: false for the host role to switch the helper
off.
The seven-line, borderless ASCII space banner carries AIppliance and
Magic Stick on two lines of a USB spacecraft, without a duplicate heading
below it. There is no caption row. The denser starfield includes dim gray stars
across all seven rows, behind the foreground artwork. Most are stationary and
only a small minority drift, one column every 24 seconds, with gentle twinkling.
The ship has a rounded hull and nacelles, without flame effects; its metal
connector disappears fully inside a slightly wider, compact PC containing
a graphics card with three large, multi-row fans enclosed
in a gray shroud and a finned heatsink, without USB or GPU text labels.
Beside the fans, a small light-gray readout shows decorative IDLE / SPIN /
READY status, artificial usage %, and TPS (tokens per second).
These slowly changing values are not live appliance metrics, even outside demo mode.
Startup inserts the stick once and triggers a decorative boot-up, accelerating
orange-accented fans only inside the case; there are no external power sparks.
The stick remains connected and the
PC stays on. The pair is centered across the terminal, including wide screens.
Gray/orange visitors and a golden floating laptop appear for about 18 seconds
roughly every two minutes, with long quiet gaps and no purple accents. The laptop
has an outlined screen, keyboard, and touchpad. Clear side stages show its full
screen and base where space permits; compact screens use a three-row lower lane.
Startup travel runs at half speed; the main docking sequence does not loop.
Animation runs continuously, including during dialogs; there is no pause/resume
control. Terminals shorter than 19 rows hide the banner to preserve working
space, without stopping the animation clock.
Animation is independent of API refreshes and works in live and offline modes,
including with --no-color. The standalone
banner module owns the artwork and timing.
For a frontend-only preview, magicstick tui --demo (or corepack pnpm tui:demo
from the built dashboard workspace) displays all pages with synthetic
sample data. The OFFLINE DEMO header distinguishes it from a real session.
This mode makes no network requests, reads no saved configuration or credentials,
and disables live actions, clipboard exports, and sign-out. It does not alter
the real client's role checks or supply runtime CR seeds. See the
offline preview instructions.
The default endpoints are:
- control-plane API:
https://api.magicstick.local - issuer:
https://id.magicstick.local/realms/magicstick - public OIDC client:
magicstick-cli
api.<mDNS-domain> is an mDNS-published HTTPRoute. Its Envoy
SecurityPolicy validates Keycloak JWTs before forwarding the request. The
public CLI client enables only Device Authorization Flow: it has no secret,
redirect URI, password grant, implicit flow, or service account. The CLI opens
the verification page when possible and prints the URL and one-time user code,
so login also works in a remote shell. Access and refresh tokens are stored in a
mode-0600 session file below the XDG configuration directory; logout removes
that local session. Password operations accept a protected file or stdin and
never a command-line password value.
Build and use the terminal client with:
cd dashboard
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm cli --help
pnpm cli login
pnpm tui
pnpm cli console
Use MAGICSTICK_API_URL, MAGICSTICK_ISSUER, and
MAGICSTICK_CLIENT_ID for a non-default deployment. A caller may provide an
existing short-lived token through MAGICSTICK_ACCESS_TOKEN; it is not cached.
The CLI also uses CAs trusted by the operating system. If the appliance-local
CA has not been installed there, pass its public certificate once with
pnpm cli --ca-file /path/to/magicstick-oidc-ca.crt login. The path is saved
in the private CLI configuration for later CLI and TUI calls. Alternatively,
set MAGICSTICK_CA_FILE or
NODE_EXTRA_CA_CERTS=/path/to/magicstick-oidc-ca.crt. The legacy --insecure
escape hatch is rejected; TLS certificate verification is required for all
CLI and TUI connections.
Physical appliance console¶
Bare-metal and Linux-host installations automatically display the TUI on the attached monitor after first-run setup is complete. The setup claim page and the operational TUI share virtual terminal 9 but never run concurrently:
magicstick-setup-console.serviceowns terminal 9 while the one-time claim exists.- Successful setup removes the claim and starts
magicstick-dashboard-console.service. - The console starts
magicstick console, which signs in automatically and opens the TUI. No browser, second device or network connection is needed.
Automatic sign-in¶
The attached monitor and keyboard are signed in as Local console with
Administrator access by default, so the appliance can be operated and
repaired at the machine itself, including while the network is unavailable.
Anyone with physical access to that keyboard has the configured access without
a password. Administrators choose the level under System → Settings → Local
console, in the TUI under System → Settings (Change, or e), or with the CLI:
magicstick console-access get
magicstick console-access set operator # off | viewer | operator | admin
| Level | Console without a login |
|---|---|
| Administrator (default) | Full access, including users, network and power. |
| Operator | Status, services and models; no administration. |
| Viewer | Read-only status. |
| Off | No automatic access; the console shows a device login. |
A change applies to the next request of a running console. A lowered or
switched-off console cannot raise its own level again; an administrator signs
in from the browser dashboard, the CLI, or on the console itself with x.
Press x to act as a different user: the console shows an address and a
one-time code that the user confirms in a browser on a second device (Keycloak
device login). Esc cancels and returns to the previous session. A signed-in
user replaces the automatic session until they choose Return to the automatic
monitor session with x. With Off, or on an appliance whose platform
revision has not provisioned automatic sign-in yet, the device login is shown
directly; it needs a second device that can reach the appliance.
The terminal client is packaged into a dedicated Node.js CLI runtime image and
executed in a dedicated runtime Deployment with no Service, no ingress and no
Kubernetes service-account token. API and token polling traffic uses cluster-internal
transport while the token issuer and browser verification address remain the
canonical id.<mDNS-domain> URL. Automatic sign-in uses a dedicated
confidential Keycloak client, magicstick-console, whose generated secret
exists only as Secret/magicstick-console-client in identity-system and is
mounted read-only into that runtime. Its service account holds dashboard roles
only: no Keycloak administration and no Kubernetes group. The CLI exchanges the
secret for a five-minute access token that is kept in memory and never written
to disk. The dashboard API honours that token only on the direct in-cluster
connection the console uses: requests that arrive through the gateway or the
browser frontend are refused, and the api.<mDNS-domain> route denies the
console identity as well. A copied secret therefore cannot be used from another
device on the network or the internet. The persistent session directory is mounted only into that runtime and
stores mode-0600 token data of a user who signed in with x; no password is
stored. Pressing q exits the current process, after which the appliance
service restores the TUI automatically.
| Method | Path | Behavior |
|---|---|---|
GET |
/api/session |
Returns the authenticated username and local realm roles. |
GET |
/api/appliance |
Returns Appliance/local. |
PATCH |
/api/appliance |
Returns 405; Appliance/local.spec is Git-owned. |
GET |
/api/settings |
Returns public domain, its derived dashboard host, mDNS domain, and derived mDNS name. |
PATCH |
/api/settings |
Validates and patches flux-system/ai-appliance-settings, keeps the dashboard host synchronized with the public domain, and preserves unrelated keys. |
GET |
/api/modules |
Returns catalog metadata plus current ModuleActivation spec/status. |
POST |
/api/modules/{name}/enable |
Creates or patches a ModuleActivation with spec.enabled: true. |
POST |
/api/modules/{name}/disable |
Creates or patches a ModuleActivation with spec.enabled: false. |
GET |
/api/modules/{name}/credentials |
Returns credentials for an enabled catalog module with an explicitly supported provider, currently LiteLLM. |
GET |
/api/instances |
Returns AppInstance resources and status. |
GET |
/api/my-instances |
Minimal granted instance launchpad for any Magic Stick user. |
GET |
/api/instance-principals |
Live admin: paginated user/group directory IDs and names. |
GET / PUT |
/api/instances/{name}/access |
Live admin: inspect sharing; updates also require entitlement, ready guard, CSRF and expected resource revision. |
GET |
/api/instances/{name}/credentials |
Returns supported generated credentials for an instance, currently OpenClaw. |
POST |
/api/instances/{type} |
Adds or replaces an AppInstance for supported types such as openclaw, hermes, odysseus, paperclip, kubeopencode, or pi-coding. |
DELETE |
/api/instances/{name} |
Deletes the AppInstance; its finalizer removes the generated HelmRelease and Helm cleans the application resources. |
GET |
/api/models |
Returns model catalog entries, variant-aware presets, compute-target availability ModelActivation resources, AnythingLLM status, the estimator-compatible VRAM summary, and a computeMemory.devices list for the CPU and every discoverable GPU resource. |
GET |
/api/models/{name}/logs?tailLines= |
Administrator-only bounded snapshot of current and, after restarts, previous output from Pods owned by the named local model. The API derives namespace, Pods, and containers from the activation and Kubernetes ownership; clients cannot select arbitrary Pods. |
GET |
/api/models/compute-targets |
Returns CPU/NVIDIA/AMD/Intel availability, supported engines and KV-cache formats, resolved resource/profile, and a non-sensitive reason when a target is unavailable. |
GET |
/api/model-discovery/search?provider={huggingface,ollama}&engine={VLLM,OLlama}&q=&cursor=&limit= |
Searches public Hugging Face repositories or prefix-matching Ollama Library model names and returns bounded metadata plus a continuation cursor. |
GET |
/api/model-discovery/popular?provider={huggingface,ollama}&engine={VLLM,OLlama}&limit= |
Returns Hugging Face trending models or Ollama's public popularity order, filtered for the selected model type, engine, compute target. |
GET |
/api/model-discovery/artifacts?provider={huggingface,ollama}&engine={VLLM,OLlama}&repo=&cursor=&limit= |
Resolves directly related Hugging Face quantizations or the selected Ollama model's locally runnable tags.. |
GET |
/api/status |
Returns runtime objects and the catalogued NVIDIA/AMD/Intel operator lifecycle from Appliance.status.hardwareOperators, including AMD compatibility profiles, host evidence and per-engine validation. |
POST |
/api/models/estimate-memory |
Estimates minimum and recommended RAM or accelerator memory for every supported local engine/compute-target/KV-cache combination; an explicit NVIDIA cpuOffloading: true plus VRAM budget returns a separate offloading RAM/VRAM plan. |
POST |
/api/models/{name}/estimate-memory |
Operator-only edit estimate for an existing local model. It merges editable runtime parameters with the deployed model identity and excludes that model's current reservation from available capacity. |
POST |
/api/models/estimate-vram |
Backward-compatible alias for /api/models/estimate-memory. |
POST |
/api/models/local |
Adds or replaces a local ModelActivation: KubeAI-backed for ordinary vLLM/Ollama or a direct Realtime runtime. |
POST |
/api/models/external |
Adds or replaces an external LiteLLM-backed ModelActivation; Dashboard-entered API keys are stored as Secrets. |
PUT |
/api/models/{name} |
Operator-only, CSRF-protected update of editable runtime/provider parameters. The request is bound to expectedRevision; model source, local engine, hardware target, namespace, and name remain unchanged. |
POST |
/api/models/{name}/start |
Re-enables a retained ModelActivation and lets its normal reconciler recreate the runtime. |
POST |
/api/models/{name}/stop |
Disables a ModelActivation; its operator-managed local runtime is removed without deleting the saved configuration. |
POST |
/api/models/{name}/restart |
Requests a safe rollout restart of a Realtime runtime by changing an operator-owned nonce; vLLM/Ollama continue to use their existing reconciliation lifecycle. |
POST |
/api/models/local-runtime/remove |
Removes model-created runtime activations after all local models have been removed; a hardware-detected GPU operator is preserved. |
DELETE |
/api/models/{name} |
Deletes the ModelActivation and a Dashboard-created provider Secret when present. |
GET |
/api/status |
Returns Appliance, Flux, Pod, Service, and Ingress status summaries. |
GET |
/api/events |
Returns core and events.k8s.io event summaries. |
GET |
/api/users?search=&first=&max= |
Searches human Keycloak users with bounded server-side pagination. |
GET |
/api/users/{id} |
Returns one sanitized human-user representation. |
POST |
/api/users |
Creates a local user with a temporary password and selected access level. |
PATCH |
/api/users/{id} |
Updates locally managed profile fields. |
PUT |
/api/users/{id}/roles |
Replaces only the direct MagicStick access roles and preserves unrelated roles. |
POST |
/api/users/{id}/enable |
Enables the account. |
POST |
/api/users/{id}/disable |
Disables the account and requests a Keycloak logout. |
PUT |
/api/users/{id}/password |
Sets a temporary local password and requests a Keycloak logout. |
DELETE |
/api/users/{id} |
Deletes an eligible local account. |
GET |
/api/api-access |
Lists only named LiteLLM virtual keys created through this dashboard plus the local/public API bases; raw key values are never returned. |
POST |
/api/api-access |
Creates a named LiteLLM virtual key and returns its raw value exactly once. |
DELETE |
/api/api-access/{id} |
Verifies dashboard ownership and revokes one named LiteLLM virtual key. |
GET |
/api/console-access |
Administrator: returns whether automatic console sign-in is provisioned and its level (off, viewer, operator, admin). |
PUT |
/api/console-access |
Administrator: replaces the dashboard roles of the local console identity with {"accessLevel": …}; effective on the console's next request and recorded in the user-administration audit log. |
GET |
/api/kubernetes-access?search=&first=&max= |
Lists human Keycloak users, their direct Kubernetes access group, and non-secret cluster OIDC readiness. |
PUT |
/api/kubernetes-access/{id} |
Replaces only the user's direct Magic Stick Kubernetes group and requests a Keycloak logout. |
GET |
/api/kubernetes-access/{id}/kubeconfig |
Returns a user-labelled kubeconfig with cluster/identity CAs and an OIDC exec plugin, but no token, password, or client secret. |
GET |
/api/federated-sso |
Admin-only sanitized state for dashboard-managed providers, capability status, stable issuer and callback template. No provider secret or raw Keycloak representation is returned. |
| Internal | /internal/federation-license |
Envoy-only entitlement decision for external Keycloak broker requests. No user authentication or identity data; exact 200 only for a verified active entitlement, otherwise deny. Local login/recovery do not use this route. |
POST |
/api/federated-sso/validate |
Entitled live admin: validates allowlisted input and asks Keycloak to import OIDC discovery or SAML metadata without saving a provider. |
POST |
/api/federated-sso/providers |
Entitled live admin: creates a provider disabled first, installs server-generated role mappers, then enables it only after the complete write succeeds. |
PUT |
/api/federated-sso/providers/{alias} |
Entitled live admin: updates an immutable alias using the expected sanitized revision; OIDC updates require the client secret again. |
DELETE |
/api/federated-sso/providers/{alias} |
Live admin: deletes a dashboard-owned provider after expected-revision confirmation. Deletion remains available without entitlement for recovery. |
All read endpoints require magicstick-viewer, magicstick-operator, or
magicstick-admin. Instance credential reads and runtime mutations require
operator or admin. Settings changes require admin. Envoy authentication alone
does not authorize a configuration change. All /api/users endpoints require
magicstick-admin, re-check that the actor is still enabled and still an
administrator in Keycloak, and return only sanitized fields and capability
flags. Mutations require the X-MagicStick-CSRF request marker. Browser
mutations additionally require valid same-origin metadata; a Bearer-authenticated
terminal client sends no browser Origin or Sec-Fetch-Site headers.
All /api/api-access endpoints require magicstick-admin; create and revoke
requests use the same same-origin and CSRF checks.
All /api/kubernetes-access endpoints require magicstick-admin and a live
Keycloak administrator check. Mutations use the same same-origin and CSRF
checks. Kubeconfig download additionally requires an enabled target user, a
non-empty grant, and a cluster-published OIDC readiness marker.