CLI Guide

The microstax CLI is the fastest way to work with MicroStax from a terminal, CI job, or script. This page keeps the common commands near the top and moves lower-frequency admin and power-user workflows lower down.

Global Options

These flags work across the command tree where relevant.

Flag	Meaning
--api, --apiUrl	Override the API base URL. Defaults to MICROSTAX_API or http://localhost:3000.
--token	Override the bearer token. Defaults to MICROSTAX_API_TOKEN.
--org	Override the organization scope. Defaults to MICROSTAX_ORG_ID.
--json	Emit machine-readable JSON instead of formatted output.
--help, -h	Show usage help.
--version, -v	Print the CLI version.
--no-color	Disable ANSI formatting.
--yes, -y	Skip interactive confirmations when supported.

Top-Level Commands

Command group	Purpose
env	Environment lifecycle, inspection, validation, replay, and diagnostics.
baseline	Baseline creation and listing.
overlay	Overlay creation, listing, and deletion.
seed	Seed publishing, search, and execution.
template	Bundled Blueprint templates.
init	Blueprint generation from an existing repository.
welcome	Interactive onboarding.
governance	Governance and audit inspection.
resilience	Mesh health and heat inspection.
sovereignty	Relocation and residency-related workflows.
org	Organization-level reports.
github	GitHub integration status.
webhook	Outbound webhook management.

Common Commands

These are the commands most developers use every day.

env Command Reference

Create and validate an environment

Syntax	What it does
microstax env validate --file <blueprint.yaml>	Validate a Blueprint without creating resources.
microstax env create --file <blueprint.yaml> [--name <name>] [--yes]	Create an environment from a Blueprint file.
microstax env create --from-compose <docker-compose.yml> [--name <name>] [--yes]	Import a Compose file and create the environment in one step.

Inspect an environment

Syntax	What it does
microstax env list	List environments in the current organization.
microstax env get <id>	Fetch environment details and endpoints.
microstax env status [<id>]	Show cluster health or one environment's status.
microstax env logs <id> [--service <name>] [--follow] [--tail <n>]	Stream or tail logs.
microstax env traces <id> [--service <name>] [--limit <n>]	Fetch distributed trace summaries.
microstax env share <id> [--ttl <hours>] [--pin <pin>]	Generate a share link.

Update lifecycle state

Syntax	What it does
microstax env set <id> --name <name>	Rename an environment.
microstax env set <id> --auto-shutdown [--delay <minutes>]	Enable auto-shutdown and optionally set the delay.
microstax env set <id> --no-auto-shutdown	Disable auto-shutdown.
microstax env stop <id>	Stop a running environment.
microstax env resume <id>	Resume a stopped environment.
microstax env delete <id>	Delete an environment.
microstax env scale <id> <service> <replicas>	Scale a service in place.

Typical first workflow

microstax env validate --file ./microstax.yaml
microstax env create --file ./microstax.yaml --json
microstax env status <env-id>
microstax env logs <env-id>

Frequent Team Workflows

These are still common, but usually show up after your team has a baseline workflow in place.

Baselines and Branch Environments (Overlays)

Syntax	What it does
microstax env promote <id>	Promote an environment to a shared baseline.
microstax baseline create --file <file>	Create a baseline directly from a Blueprint file.
microstax baseline list	List active baseline environments.
microstax overlay create --baseline <id> --file <overlay.yaml>	Create a developer overlay.
microstax overlay list [--baseline <id>]	List active overlays.
microstax overlay delete <id>	Delete an overlay environment.

Data workflows

| Syntax | What it does | | ------------------------------------------------------------------------------------------ | ------------------------------------------------ | -------------------------------- | | microstax env seed <id> --service <name> [--script <path>] [--timeout <seconds>] | Run a seed script in an environment. | | microstax env snapshot create <id> [--service <name>] | Create a production-safe snapshot. | | microstax env snapshot list <id> | List snapshots for an environment. | | microstax env snapshot closure <id> | Create an immutable snapshot package for replay. | | microstax seed publish <file> --name <name> --version <v> --service <target> [--type <sql | shell>] [--description <text>] | Publish a reusable seed package. | | microstax seed search [<query>] | Search the seed registry. | | microstax seed run <name> <env-id> [--version <v>] | Run a published seed package. |

Advanced Workflows

| Syntax | What it does | | --------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------- | | microstax env cost <id> | Show environment cost analysis and savings. | | microstax env diffs <id> | Review behavioral differences between compared environments. | | microstax env predictions <id> | Fetch Blueprint prediction insights. | | microstax env diagnose <id> [--apply] | Run AI troubleshooting and optional fixes. | | microstax env replay <id> [--snapshot <id>] | Re-run an environment from its history or a selected snapshot. | | microstax env shadow <id> <--enable | --disable> | Enable or disable behavioral shadowing (Patent 09). |

Other Top-Level Commands

Governance, Resilience, and Sovereignty

Syntax	What it does
microstax governance logs	Inspect governance audit logs.
microstax governance registry	Inspect health and compliance policies.
microstax resilience list	View mesh health and heat scores.
microstax sovereignty relocate <id> <target>	Move an environment between regions.
microstax org compliance	Generate an organization compliance report.

Integration and Automation

Syntax	What it does
microstax template list	List bundled Blueprint templates.
microstax init	Scan the current repository and generate microstax.yaml.
microstax welcome	Run the interactive onboarding flow.
microstax github status	Show GitHub integration status.
microstax webhook list	List outbound webhook subscriptions.
microstax webhook create <url> [events,comma,separated]	Create an outbound webhook subscription.
microstax webhook delete <id>	Delete an outbound webhook subscription.

JSON Output And Automation

Use --json whenever the output needs to be parsed by another tool.

microstax env create --file ./microstax.yaml --json
microstax env get env_123 --json
microstax seed search payments --json

Operational notes:

• env logs uses a WebSocket streaming transport in the current CLI implementation.
• env traces reads from the Jaeger endpoint configured by MICROSTAX_JAEGER or http://localhost:16686.
• Most mutating commands call the REST API and treat provisioning as asynchronous.

[!NOTE] Deep Dive: Some advanced commands surface patent-backed capabilities such as replay, sparse cost analysis, behavioral diffing, and sovereignty workflows. This page keeps those features practical first and leaves the formal patent mapping to the deeper docs.