MoiraWeave CLI

Developer CLI for creating and operating MoiraWeave workspaces.

MoiraWeave is a self-hosted operations platform for AI workloads: model services, pipelines, and agent runtimes. The CLI owns the local user workflow: workspace init, workload manifests, runs, agent sessions, and deployment asset generation.

Install

uv tool install moiraweave-cli
moira --help

This install command uses PyPI. PyPI is not required by the MoiraWeave runtime once the CLI has generated or started the stack: API Gateway, worker, UI, storage services, workloads, and the Helm chart run from GHCR images. If PyPI is not available, use a local checkout with uv tool install . from this repository, or run the published CLI image when operating from CI or Kubernetes: ghcr.io/moiraweave-labs/moiraweave-cli:latest.

Quickstart

mkdir my-moiraweave-workspace
cd my-moiraweave-workspace
moira up
moira agent chat demo-agent "hello from the CLI" --watch

moira up initializes the workspace if needed, creates a no-secret demo agent when there are no workloads, writes a local docker-compose.yml with the Ops dashboard enabled, generates workload Compose services, runs moira doctor, starts API, worker, storage, UI, and workloads, waits for API and UI readiness, and registers local deployment records. The dashboard is available at http://localhost:3000. Open http://localhost:3000/agents after sign-in to land directly in the agent console; the first agent and any existing session are selected automatically.

Use moira doctor whenever the local stack does not start cleanly:

moira doctor
moira doctor --json
moira workload preflight demo-agent

Doctor prints both the raw checks and a deployment readiness guide. For real agents such as Hermes or OpenClaw, the guide turns missing secrets, Docker issues, generated Compose gaps, API/UI reachability, and deployment record gaps into concrete next commands. The --json output includes the same action_guide data for automation. Use moira workload preflight <name> after a workload exists in the API to run the control-plane checks for that specific runtime, target, and environment.

For development or private registries, override platform images in .env: MOIRAWEAVE_API_GATEWAY_IMAGE, MOIRAWEAVE_WORKER_IMAGE, and MOIRAWEAVE_UI_IMAGE.

Official platform images are built and pushed by GitHub Actions. For a clean first run without docker login ghcr.io, the GHCR packages must also be public: moiraweave/api-gateway, moiraweave/worker, and moiraweave-ui. Transient registry timeouts, 429s, or temporary GHCR issues are reported as warnings by moira doctor; private, missing, or denied images remain blocking errors.

The CLI also publishes ghcr.io/moiraweave-labs/moiraweave-cli:latest. That image includes moira, Helm, and kubectl so it can run the Kubernetes deployment controller inside a cluster, CI runner, or operator shell. The Docker workflow keeps Trivy strict for the image and temporarily excludes only /usr/local/bin/kubectl while the latest stable upstream kubectl embeds a vulnerable golang.org/x/net; remove that exclusion as soon as Kubernetes publishes a rebuilt stable binary.

Start from another agent template when you want the first run to be a real runtime instead of the demo:

moira up --agent hermes
moira up --agent openclaw
moira up --agent external-agent --agent-endpoint https://agent.example.com

Hermes/OpenClaw templates validate required secrets before Docker starts. Add them to .env or export them in the shell. Use moira up --agent demo-agent for a no-secret first run. Their web search, browser, terminal, MCP, memory, and native channel tools stay inside the agent runtime; MoiraWeave only prepares the declared deployment boundary and observes health, runs, events, and artifacts through the adapter.

For Kubernetes, keep values in Kubernetes Secrets or an external secret manager. The CLI can verify key names without printing values:

moira secrets list --target kubernetes --env dev --kubernetes-secret moiraweave-secrets

Command Surface

• moira init: create a MoiraWeave workspace.
• moira up --agent demo-agent|hermes|openclaw|generic-http-agent|external-agent: initialize if needed, start the local stack, and register workloads.
• moira doctor: diagnose local onboarding blockers before Docker starts.
• moira demo agent: create a no-secret mock agent workload.
• moira workload new|list|show|deploy|status|preflight|logs: manage workload manifests.
• moira run submit|list|watch|cancel|events|artifacts: operate workload runs. Use moira run list --env prod and moira run artifacts <run-id> --env prod when you need the same environment-focused view as the UI.
• moira run dead-letter list|replay|purge: inspect, recover, or clean failed dispatch messages.
• moira agent chat: create a session if needed and send one message.
• moira agent session create|message|history: interact with agent sessions.
• moira agent channel-message: simulate Telegram, Slack, Discord, or webhook ingress. The channel must be listed in the agent workload's spec.agent.exposedChannels.
• moira deploy local|k8s: generate Compose or Helm values from workload manifests.
• moira deploy controller run: claim queued Kubernetes deployment operations and execute Helm/kubectl outside the UI.
• moira env list: inspect environment-scoped deployment and operation counts.
• moira ops alerts: inspect actionable retry, lost-run, dead-letter, and deployment-operation alerts.
• moira secrets list: inspect required secret names from local .env, shell environment, or Kubernetes Secret keys.
• moira security me: show the current subject, role, credential type, and team scope.
• moira security bootstrap-admin: create the first persistent admin when demo auth is disabled.
• moira security user list|create|update|enable|disable|password-change|password-reset: manage persistent users.
• moira security team list|create|update|members|add-member|remove-member: manage teams and memberships.
• moira security api-key list|create|rotate|revoke: manage hashed API keys; create and rotate print one-time secrets.

Use --channel for channels MoiraWeave owns through its API gateway. Use --external-channel telegram when the agent runtime owns Telegram directly and MoiraWeave should only supervise the workload.

Identity commands talk to the API gateway and use MOIRA_TOKEN or the workspace token saved by moira up. API keys can optionally be scoped with --team-id so automation runs as a team-aware operator instead of a global admin.

Workspace Model

your-workspace/
  moiraweave.yaml
  .env
  .moiraweave/
    workloads/
    artifacts/
    deploy/

Workloads are ordinary YAML manifests. MoiraWeave deploys and observes the runtime, but model and agent internals stay inside the workload image.

Development

uv sync --frozen
uv run ruff check moira_cli tests
uv run mypy moira_cli
uv run pytest

Related Repositories

• moiraweave: runtime services and infrastructure
• moiraweave-ui: integrated Ops dashboard
• moiraweave-docs: documentation site