Install and authenticate

miosa is the official MIOSA command line tool. There is one miosa CLI: version 2.2. It runs on macOS, Linux and Windows.

Install

Verify

miosa --version
miosa version

These print 2.2.0. If they print 1.x, run npm i -g @miosa/cli@latest or brew upgrade to move onto the 2.x line.

Windows

The npm install is the simplest path on Windows: npm i -g @miosa/cli resolves the win32-x64 build (@miosa/cli-win32-x64) and puts miosa on your PATH.

To install by hand, download miosa_2.2.0_windows_amd64.zip from GitHub Releases, extract miosa.exe, and add its folder to your PATH. In PowerShell:

$dir = "$env:USERPROFILEmiosa"
Expand-Archive -Path "$env:USERPROFILEDownloadsmiosa_2.2.0_windows_amd64.zip" -DestinationPath $dir
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$dir", "User")

# open a new terminal, then
miosa --version

SetEnvironmentVariable with the User scope makes the change permanent without admin rights; it only affects terminals opened after you run it. For the current session only, use $env:Path += ";$dir" instead.

Windows builds are x64 only. There is no windows/arm64 archive.

Upgrading from 1.x

1.x was the Node CLI. 2.x is the same miosa command with a rewritten command surface, and the installs above now all give you 2.2.x.

What changed:

• Sandbox commands lost the sandbox prefix. miosa sandbox create is now miosa create.
• Deployment work moved under miosa deploy. The old miosa app and top-level releases, rollback and builds commands are now miosa deploy subcommands. New in 2.2: miosa deploy create publishes a sandbox, a git repository or a local directory.
• Contexts became profiles. miosa context is now miosa profile, stored in ~/.miosa/config.toml.
• Restored in 2.1. Several 1.x command families came back, renamed: miosa device (any runtime kind), miosa mcp, and the miosa host families for containers, meshes, GitHub Actions runners, backups and tunnels.
• Still removed from the public CLI: the internal OSA tooling actions, blueprint, changes, drift, evidence, capabilities and command-overview. Action authority is server-side, and miosa --help replaces command-overview.

Renamed commands:

Update

miosa update            # download and replace the binary
miosa update --check    # report only
miosa version

miosa update verifies the SHA-256 of the download against the release checksums.txt, and refuses to replace a Homebrew-managed binary (use brew upgrade there). A one-line notice appears at most once a day when a newer version exists; silence it with --no-update-notice or MIOSA_NO_UPDATE_NOTICE=1.

Shell completion

miosa completion zsh      # bash, fish, powershell

Sandbox names, profiles, templates and agents complete from the live API.

Sign in

miosa login               # opens the browser, device-code sign in
miosa whoami              # organization, plan, credits, and the scopes your key holds

miosa whoami shows the user, organization, workspace, plan and the scopes the key holds.

Sign in with a key

miosa login --with-key asks for a key with hidden input, and --key-stdin reads it from stdin. A key is never accepted as an argument.

miosa login --with-key
echo "$MIOSA_KEY" | miosa login --key-stdin

Credential resolution

Credentials resolve in this order:

1. --api-key
2. MIOSA_API_KEY
3. the active profile in ~/.miosa/config.toml

Sign out

miosa logout

Removes the stored key of the active profile. miosa logout --all deletes the config file for every profile.

Diagnose

miosa doctor

Checks configuration, connectivity and authentication, and prints a fix for each failure.