Miabi CLI MCP server

miabi CLI

The imperative client for a Miabi control panel. Drive the deploy flow from a terminal or CI — miabi apps deploy web --tag $SHA --wait updates the image, deploys, blocks until the deployment is terminal, and exits non‑zero on failure.

It is also the tool that installs and manages a Miabi host: miabi setup stands the stack up on a machine and miabi upgrade moves it forward. Those commands talk to the local Docker socket, not to a panel — see Managing a host.

Install

Homebrew (macOS & Linux) — from the miabi-io/homebrew-tap:

brew install miabi-io/tap/miabi

Homebrew 6 requires third-party taps to be trusted before the short form works:

brew tap miabi-io/tap
brew trust miabi-io/tap
brew install miabi

Windows (PowerShell, no admin rights needed):

irm https://raw.githubusercontent.com/miabi-io/cli/main/install.ps1 | iex

It installs miabi.exe to %LOCALAPPDATA%\Programs\miabi and adds that folder to your user PATH. Set MIABI_CLI_VERSION to pin a version, or MIABI_INSTALL_DIR to install elsewhere.

Go:

go install github.com/miabi-io/cli@latest   # installs the `miabi` binary

Prebuilt binary — download from the GitHub Releases page, or grab the archive for your platform directly (Linux x86_64 shown):

VERSION=0.4.0
curl -fsSL "https://github.com/miabi-io/cli/releases/download/v${VERSION}/miabi_${VERSION}_linux_amd64.tar.gz" \
  | tar -xz miabi && sudo mv miabi /usr/local/bin/
miabi --version

(Swap linux_amd64 for linux_arm64, linux_armv6 (32-bit Raspberry Pi OS), darwin_amd64, darwin_arm64, or use the .zip for Windows.)

Docker — no install at all; handy in CI. Published to Docker Hub and mirrored to GHCR (ghcr.io/miabi-io/cli):

# check the connection
docker run --rm -e MIABI_SERVER -e MIABI_TOKEN miabi/cli:latest whoami

# deploy from a pipeline — exits non-zero if the rollout fails
docker run --rm -e MIABI_SERVER -e MIABI_TOKEN \
  miabi/cli:latest apps deploy web --tag "$GIT_SHA" --wait

# mount a manifest to apply it declaratively
docker run --rm -e MIABI_SERVER -e MIABI_TOKEN -v "$PWD:/work" -w /work \
  miabi/cli:latest apply -f stack.yaml

Authenticate

The CLI resolves its context as flags → env → ~/.miabi/config.yaml:

export MIABI_SERVER=https://miabi.example.com
export MIABI_TOKEN=mb_…            # an API key with the `deploy` scope

# …or persist it:
miabi --server "$MIABI_SERVER" --token "$MIABI_TOKEN" login

~/.miabi/config.yaml (written by login / workspace switch, mode 0600) holds one or more named contexts — each a server + token + bound workspace/app — and the active one:

current: acme-prod
contexts:
  acme-prod:
    server:
      url: https://miabi.example.com
      ca: /etc/ssl/miabi-ca.pem   # optional: trust a private CA
      insecure_skip: false        # optional: skip TLS verification
    token: mb_…
    workspace: { id: 42, name: acme-prod, display_name: Acme Prod }
  staging:
    server: { url: https://staging.example.com }
    token: mb_…

Contexts (switch between servers)

miabi login writes a context (named by --context, else the server host). Switch between them, or target one for a single command:

miabi login --context prod    --server https://miabi.example.com --token mb_…
miabi login --context staging --server https://staging.example.com --token mb_…

miabi context ls              # list contexts (→ marks the current)
miabi context use staging     # switch the active context
miabi --context prod apps ls  # run one command against another context
miabi context current         # print the active context name
miabi context delete staging  # remove a context

TLS trust per context: --certificate-authority <ca.pem> (env MIABI_CA) and --insecure-skip-tls-verify (env MIABI_INSECURE_SKIP_TLS_VERIFY). Older flat/ single-server config files are migrated into a default context automatically.

Commands

Every app command lives under apps and takes the app as its first argument — or you can bind a default once with miabi use <app> and omit it:

miabi whoami                       # identity, scopes, active workspace + app
miabi workspace ls|show|switch     # set the active workspace context (alias: ws)
miabi workspace migrate --from old --to new -w acme   # move a workspace to another Miabi
miabi use web                      # bind a default app (per workspace)

miabi apps ls                      # list applications (→ marks the bound app)
miabi apps create web (--image miabi/guestbook [--tag 1.0] | --git-repo <url> [--git-ref main]) [--port 3000] [--use]
miabi apps deploy      [web] --tag $SHA [--strategy rolling] [--no-cache] [--wait] [--timeout 10m]
miabi apps start|stop|restart [web]               # control the app's container
miabi apps deployments [web]                      # deploy history — the NUMBER column
miabi apps logs        [web] [--follow] [--tail 200]      # current logs (‑‑follow to stream)
miabi apps logs        [web] --deployment 7               # a deployment's build logs
miabi apps set-source  [web] (--image nginx --tag 1.27 | --git-repo <url> --git-ref main)
                                                  # switch image <-> git in place; keeps domains,
                                                  # env, volumes, databases and history
miabi apps resync-pipeline [web]                  # reload the repo's pipelines.yaml (adopt or sync)
miabi apps invalidate-cache [web]                 # next build rebuilds every layer
miabi apps status      [web] [--deployment 7]
miabi apps releases    [web]
miabi apps rollback    [web] (--to <version> | --to-previous) [--yes]
miabi apps env ls      [web]                              # secret values are masked
miabi apps env set     [web] KEY=VALUE [--secret]
miabi apps env set     [web] KEY --from-file f [--secret] # value from a file/stdin — no shell history
miabi apps env import  [web] --from-file .env [--secret]  # "-" reads stdin

miabi pipeline ls                                 # CI/CD pipelines in the workspace
miabi pipeline run   <pipeline> [--branch main] [--commit <sha>] [--no-cache]
miabi pipeline rerun <run-id> [--no-cache]        # same commit again, optionally cold

miabi apply  -f stack.yaml [--prune] [--dry-run]  # declarative: converge to a manifest bundle
miabi delete -f stack.yaml [--dry-run]            # delete exactly the resources the bundle names

Managing a host

setup, upgrade and system … are the exception to "API client": they act on the machine they run on, through its Docker socket, and never call the HTTP API. This is what curl -fsSL https://get.miabi.io | sudo bash installs and then runs.

miabi setup [--domain miabi.example.com] [--image miabi/miabi:1.7.3] [--yes]
                                              # install, or converge an existing install
miabi upgrade [component] [--version 1.8.0 | --image <ref>] [--yes]
                                              # roll forward; rolls back if it never gets healthy
miabi system status                           # what runs, its health, drift from the manifest
miabi system restart [component] [--yes]      # restart in place, re-reading on-disk config
miabi system env set KEY=VALUE                # change the manifest's env; `system apply` makes it live
miabi system backup                           # dump the platform database (`backups`, `restore`)
miabi system uninstall [--volumes] [--yes]    # --volumes also destroys the database
miabi system config migrate                   # /etc/miabi/stack.yaml -> /etc/miabi/miabi.yaml

These commands were miabi stack … before; that spelling still works and prints the new one.

All of them need root and a Linux or macOS Docker host. setup is idempotent: re-run it and the stack converges to /etc/miabi/miabi.yaml, keeping the stored secrets. -f, --file points at a different manifest.

setup and upgrade install the latest published Miabi release, looked up when the command runs. The version is not baked into the binary: the CLI releases on its own cadence, so a stamp would pin every install to whatever was current when the CLI was built, and an older CLI could never install today's Miabi. To choose a version yourself — or to install with no network at all:

• --version 1.8.0 (a leading v is fine) swaps only the tag, keeping the current registry and repository — so it stays correct on a private registry, and on components that are not miabi/miabi: miabi upgrade miabi-gateway --version 0.14.0.
• --image <ref> replaces the reference outright. The two are mutually exclusive.

A floating tag (latest, edge, main, …) warns, and not on style grounds: the rollout skips its automatic rollback when the previous reference equals the new one, so a failed :latest upgrade has nothing to return to — and drift against it cannot be detected, so the next upgrade reports "already at" and does nothing.

Databases

Managed database instances (PostgreSQL, MySQL, MariaDB, Redis, MongoDB, libSQL) and the logical databases hosted on them. Instances are addressed by slug (or numeric id):

miabi db ls                                   # list instances
miabi db engines                              # engines + default versions
miabi db create shop --engine postgres [--version 16] [--size-mb 2048] [--node <id>]
miabi db get shop
miabi db start|stop|restart shop
miabi db logs shop [--follow] [--tail 200]
miabi db credentials shop                     # reveal admin connection (admin)
miabi db upgrade shop --to 17 [--stop-apps]
miabi db rm shop [--yes]
# logical databases on an instance:
miabi db databases shop                       # list
miabi db databases create shop app_prod [--app web]   # optionally attach to an app
miabi db databases connection shop app_prod   # reveal connection (admin)
miabi db databases rm shop app_prod [--yes]
# link to an app (injects DB_URL, DB_HOST, … ; Redis injects REDIS_*):
miabi db link shop app_prod --app web [--prefix ANALYTICS]
miabi db link shop app_prod --app web --env url=SPRING_DATASOURCE_URL --env database_url=
miabi db link cache --app web                 # Redis: link the whole instance
miabi db links --app web                      # what is linked, and the vars it injects
miabi db unlink shop app_prod --app web

Volumes

Persistent storage for applications. Volumes are addressed by name (or numeric id) and are immutable: capacity and driver options are fixed at creation, so there is no set — recreate the volume to change them.

miabi volumes ls                              # list volumes (alias: vol)
miabi volumes create web-data --size-mb 5120 [--node <id>]
miabi volumes get web-data                    # details + the apps mounting it
miabi volumes attach web-data --app web --path /var/lib/data
miabi volumes detach web-data --app web       # unmount; the data is kept
miabi volumes rm web-data [--yes]             # destroys the data
miabi volumes storage                         # workspace totals + plan limit

SIZE is the capacity you declared; USED is what the panel last measured on disk — - means it has never been measured, which is not the same as empty. attach and detach flag the app as needing a redeploy; the mount takes effect on the next miabi apps deploy.

The default driver is local: a node-local (rwo) volume only one node can mount, so an app backed by one cannot be replicated. nfs and cifs create shared (rwx) storage every replica can mount, and host binds an operator-managed path (privileged workspaces only):

miabi volumes create shared --driver nfs \
  --driver-opt device=:/export --driver-opt o=addr=10.0.0.5,rw

# a CIFS password belongs in a file, not in your shell history:
miabi volumes create shared --driver cifs --driver-opt device=//nas/share \
  --driver-opt-file o=mount-opts.txt

Driver options are encrypted server-side and never read back. A volume declared as kind: Volume in a manifest is owned by miabi apply — change it there.

Volume contents

Read and write a volume's files without a shell on the host. The panel does this with a short-lived helper container, so the first call on a node may pause while that image is pulled.

miabi volumes ls-files web-data [--path conf]     # recursive listing (alias: files)
miabi volumes cp ./nginx.conf web-data:/conf/nginx.conf   # upload
miabi volumes cp web-data:/conf/nginx.conf ./nginx.conf   # download
miabi volumes cp web-data:/dump.sql - | gzip > dump.sql.gz
miabi volumes rm-file web-data conf/nginx.conf [--yes]

Exactly one side of cp is qualified as <volume>:<path>; the other is a local path, or - for stdin/stdout. Paths inside a volume are relative to its root, so the leading slash is optional. Uploading overwrites the file in the volume; downloading refuses to overwrite an existing local file unless you pass --force. Files are buffered in memory on both ends and the panel caps a single upload at 512 MiB — miabi db is the right tool for a database dump, not this.

rm-file on a directory removes everything under it; the prompt says how many entries that is.

Volume backups (S3)

Archive a volume's contents to the workspace's S3 target and restore them. Configure S3 in the panel's backup settings first — without it every call here is refused. Backups are addressed by the numeric ID the listing shows.

miabi volumes backups web-data                     # history
miabi volumes backups run web-data [--wait] [--timeout 1h]
miabi volumes backups logs web-data 42             # a run's full log
miabi volumes backups restore web-data 42 [--yes]  # overwrites the volume
miabi volumes backups rm web-data 42 [--yes]       # deletes the record and its archive
miabi volumes backups verify web-data 42           # still in the bucket, still openable?
miabi volumes backups pin web-data 42              # exempt a recovery point from retention

run hands the work to the panel's worker and returns while the run is still pending. --wait blocks until it settles and exits non-zero if it fails, so a CI step can depend on it.

restore overwrites the volume's current contents and does not stop the apps mounting it — stop them yourself unless the workload tolerates its filesystem changing underneath. The panel restores inline, so the command blocks until the restore finishes.

rm deletes the record and its archive in the bucket.

On Enterprise each backup is a recovery point: it has a ref such as mbvol_web-data_20260921T030000Z, is sealed under the workspace backup passphrase when one is set, and is verified as soon as it lands. verify repeats that check and exits non-zero when it fails; pin / unpin exempt a point from schedule retention. Schedules are managed in the panel.

Moving an app to another location (Enterprise)

miabi apps migrate web --location eu-east --plan            # what would move, and what blocks it
miabi apps migrate web --location eu-east                   # confirm, then follow it to the cutover
miabi apps migrate web --location eu-east --db shop-db=new  # restore a shared database into a new instance
miabi apps migrate web --location eu-east --cutover manual  # copy the data, then wait
miabi migrations [web]                                      # history
miabi migrations show 12
miabi migrations cutover|cancel|rollback|finalize 12

The data is copied while the app keeps serving; the app stops only for the final copy and a deploy. --db takes INSTANCE=move, =new or =existing:<instance-id>. migrate exits non-zero when the move fails or is rolled back. The old copy is kept for 7 days: rollback returns to it (changes made since the cutover are lost), finalize deletes it now.

Moving a workspace to another Miabi

Both servers need MIABI_MIGRATION_ENABLED=true. The workspace's owner starts a migration on the source and gets a migration code, shown once; the target imports the workspace with it. A workspace code works for one completed import and then closes itself; it also expires (24h by default, 7 days at most) and can be cancelled. Starting again replaces the open code.

# on the source
miabi workspace migration start -w acme [--expires 6h]   # prints the code once
miabi workspace migration status -w acme                  # open migration, frozen state, past imports
miabi workspace migration cancel -w acme                  # the code stops working

# on the target: paste the code when asked (keeps it out of your shell history)
miabi workspace import --code-file - [--freeze] [--deploy] [--retire] [--new-name acme-eu]

import first shows what the code opens (apps, databases, volumes, size), then asks to go ahead, follows the move and prints the report. A platform admin can open every workspace with miabi workspace migration start --instance; the target then picks one with -w <workspace>.

With both servers saved as contexts (miabi login --context old …, miabi login --context new …), one command starts the migration on the source, imports on the target, follows the move and prints the report:

miabi workspace migrate --from old --to new -w acme --rehearse   # configuration only, to check the move
miabi workspace migrate --from old --to new -w acme --freeze --deploy
miabi workspace migrate --from old --to new -w acme --new-name acme-eu --retire --yes
miabi --context old workspace unfreeze -w acme                   # roll a frozen source back

You must own the workspace on the source. --freeze stops the source's apps for a consistent copy (a failed move unfreezes it); --retire marks the source as moved once the import succeeds; --no-data skips the database dumps and volume archives. --source-insecure-skip-tls-verify and --source-ca are for the target reaching the source; the CLI itself trusts each server as its context says. migrate cancels the migration on the source unless the import completed (a completed import closes it already). import and migrate exit non-zero when the migration fails and warn when it ends partial.

Secrets

The workspace vault: values encrypted at rest, write-only over the API, and referenced from an app's env as ${{ secrets.NAME }}. Secrets are addressed by name (or numeric id). Supply a value with --from-file or stdin to keep it out of your shell history.

miabi secrets ls                              # list secrets (no values)
miabi secrets get API_KEY                     # details: description, version, created/updated
miabi secrets set API_KEY --from-file api.key # create, or rotate if it exists
cat api.key | miabi secrets set API_KEY --from-file -
miabi secrets set API_KEY --description "..." # keep the value, edit metadata
miabi secrets reveal API_KEY                  # print the value (admin; audited)
miabi secrets usage API_KEY                   # apps referencing it
miabi secrets rm API_KEY [--yes]

Sealed secrets

seal encrypts a value to the workspace's public sealing key and prints a kind: SealedSecret manifest, safe to commit. Encryption is local; only this workspace can open the value, and only for a SealedSecret of the same name. miabi apply and GitOps open it on the server and store it in the vault, where apps reference it as ${{ secrets.NAME }}.

echo -n "$API_KEY" | miabi secrets seal API_KEY >> secrets.yaml
miabi secrets seal API_KEY --from-file api.key --raw    # just the sealed value
miabi secrets seal-key > .miabi/sealing.pub             # public key, safe to commit
miabi secrets seal API_KEY --from-file api.key --public-key-file .miabi/sealing.pub   # offline, e.g. in CI
miabi secrets seal -f secrets.yaml --in-place           # turn every plaintext Secret into a SealedSecret

[web] is optional when an app is bound with miabi use. Deployments and releases are addressed by their per-app number/version (the NUMBER / VERSION columns), not the global platform id. Shell completion (miabi completion <shell>) tab-completes app slugs.

Declarative apply

miabi apply converges a workspace to a bundle of miabi.io/v1 manifests (the same contract GitOps uses). See docs/stack.yaml for a complete, valid example (volume, generated secret, Postgres, app with mounts + {{ .databases.* }} / {{ .secrets.* }} interpolation, domain, route):

miabi apply -f docs/stack.yaml --dry-run  # preview the plan (+ creates, ~ updates, - deletes)
miabi apply -f app.yaml -f db.yaml        # multiple files → one bundle
miabi apply -f gitops/prod                # every .yaml/.yml under the directory, as a Git source reads it
cat stack.yaml | miabi apply -f -         # stdin
miabi apply -f docs/stack.yaml --prune    # also delete managed resources absent from the bundle

It prints the plan, applies it, and exits non-zero if any resource fails to converge.

miabi delete -f is the inverse: it removes exactly the resources the bundle names (in dependency-safe order, dependents first), skipping any that don't exist:

miabi delete -f docs/stack.yaml --dry-run   # preview what would be deleted
miabi delete -f docs/stack.yaml             # delete them

Each document is { apiVersion: miabi.io/v1, kind, metadata: { name }, spec: { … } }. Kinds: Application, Stack, Database, Volume, Secret, Config, Registry, Middleware, Route, Domain, Project. Names match ^[a-z0-9][a-z0-9-]*$ (Domain names are FQDNs); use a hyphen-free name for anything referenced via dotted {{ .secrets.<name> }} / {{ .databases.<name>.* }} interpolation.

• The app argument is a slug (or numeric id); the workspace comes from --workspace, the active workspace, or a workspace‑bound token.
• -o json|yaml (or the --json shorthand) gives jq/yq‑friendly output; human tables otherwise. Color auto‑disables off a TTY, with --no-color, or when NO_COLOR is set.
• --verbose logs every HTTP request to stderr.

AI agents (MCP)

miabi mcp runs a Model Context Protocol server so an AI agent (Claude Desktop, Claude Code, Cursor, …) can inspect and operate your panel. It turns each tool call into one authenticated /api/v1 request — the agent inherits your token, workspace, and RBAC. No model runs inside miabi; you bring your own AI client.

It exposes three MCP surfaces:

• Tools — list/get apps, deployments, releases, databases, location migrations, and secret names. Read-only by default; --allow-write adds the mutating tools (deploy_app, restart_app, start_app, stop_app, rollback_app), annotated as destructive so clients prompt before calling them. Secret values are never returned.
• Resources — apps and deployments as miabi://workspaces/{ws}/apps/{app}[/deployments/{n}] URIs an agent can attach as context.
• Prompts — ready-made diagnostics: diagnose_deployment, app_health, workspace_overview.

Transport is stdio by default; pass --http 127.0.0.1:8765 to serve over HTTP instead (loopback-only origins are enforced to prevent DNS-rebinding).

# Register with Claude Code (read-only), using your current login/context:
claude mcp add miabi -- miabi mcp