Back to Documentation
Guide

CLI Guide

Automate your development workflow with the MicroStax CLI. Manage environments without leaving your terminal.

Quick Start

1

Installation

Install the CLI via curl or Homebrew. Supports macOS, Linux, and WSL2.

$curl -sL https://microstax.ai/install.sh | sh
2

Authentication

Connect to your MicroStax account and select your default organization.

$mstax auth login
3

Cluster Setup

Connect your k3s cluster to MicroStax for orchestration.

$mstax cluster connect --name my-cluster
4

Deploy Environment

Spin up an ephemeral environment using a blueprint file.

$mstax up -b ./blueprint.yaml
5

List Environments

View all active and hibernated environments in your cluster.

$mstax list

Authentication

mstax auth login opens a browser window for OAuth. Once authenticated, credentials are stored in ~/.config/mstax/credentials.json.

mstax auth loginInteractive login via browser.
mstax auth statusPrint the currently authenticated user and org.
mstax auth logoutClear stored credentials.
mstax auth tokenPrint the current auth token (useful for scripting).
Tip: For CI/CD, use a service token instead of personal credentials. Generate one at Dashboard → Settings → API Keys and set it as MSTAX_TOKEN in your environment.

CI/CD Integration

The CLI is designed to run non-interactively in CI environments. Set the MSTAX_TOKEN environment variable and the CLI will skip the browser flow.

GitHub Actions

- name: Deploy Preview Environment
  env:
    MSTAX_TOKEN: ${{ secrets.MSTAX_TOKEN }}
  run: |
    curl -sL https://microstax.ai/install.sh | sh
    mstax up -b ./blueprint.yaml --name "pr-${{ github.event.number }}" --wait
    mstax list --json | jq '.[] | select(.name=="pr-${{ github.event.number }}") | .url'

GitLab CI

preview:
  stage: deploy
  script:
    - curl -sL https://microstax.ai/install.sh | sh
    - mstax up -b ./blueprint.yaml --name "mr-${CI_MERGE_REQUEST_IID}" --wait
  variables:
    MSTAX_TOKEN: $MSTAX_TOKEN  # Set in GitLab CI/CD Variables

Command Reference

mstax up -b <file>Create an environment from a blueprint.
mstax down <id>Tear down an environment.
mstax listList all environments.
mstax status <id>Show detailed environment status.
mstax logs <id>Stream logs from all services in an environment.
mstax snapshot <id>Capture a snapshot of an environment.
mstax cluster connectLink a k3s cluster to your organization.
mstax cluster listList connected clusters.
mstax blueprint validate <file>Validate a blueprint YAML file locally.

Questions or feature requests?

The CLI is open-source. File an issue or contribute on GitHub.

View CLI source on GitHub