Skip to content

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:

  1. magicstick-setup-console.service owns terminal 9 while the one-time claim exists.
  2. Successful setup removes the claim and starts magicstick-dashboard-console.service.
  3. 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.