CLI overview

The suya CLI is the primary interface to Subaya — for humans, AI agents, and CI alike. Everything you can do through the platform starts here; the web console at subaya-dev.com is for results, waveforms, reports, and review. See Core concepts for the mental model and the Quickstart to go from install to a passing simulation.

Global flags

These flags work on every command:

Flag	Description
--host <url>	Target API host. Defaults to https://subaya-dev.com.
--token <token>	Use an explicit auth token for this invocation.
--json	Emit machine-readable JSON output.
--pretty	Pretty-print output for humans.
-q, --quiet	Suppress non-essential output.
-v, --verbose	Print extra diagnostic detail.

--json pairs well with agents and CI; --pretty is the friendly default for a terminal.

Project config — .subaya/config.toml

Most project-scoped commands read their default --project from a local .subaya/config.toml file. Once a project is initialized in a directory (see suya project), commands like suya project show, suya sim run, and suya repo status operate on that project without you passing --project every time. Pass --project <project-id> explicitly to override.

Authentication

Two modes resolve against the same API — full details in Authentication & API keys and the suya auth reference:

• SUBAYA_API_KEY — an environment variable for agents and CI. No browser.
• suya auth login — OAuth browser flow for human developers.

export SUBAYA_API_KEY="sk_..."
suya auth whoami

Command groups

Group	What it does
suya auth	Sign in, sign out, and inspect your identity.
suya project	Create, list, and manage projects and phases.
suya sim	Run cloud simulations and inspect results.
suya hw	Hardware validation runs and agent management (BitCrucible).
suya rag	Search and read the knowledge base.
suya plan	Planning documents, work items, and diagrams.
suya repo	Create or connect a GitHub repo for a project.
suya device	Browse the device catalog and assign a device.
Session	suya attach / suya detach your session pod.

More command groups

These groups round out the surface:

• suya arch — architecture and embedded pin planning (modules, pin-plans, peripheral/clock config, validate, generate, .ioc commit).
• suya req — add and list a project’s requirements (suya req add, suya req list).
• suya review — code and design reviews (create, show, list, comment, reply, resolve, approve, and more).
• suya diagram — author and render Mermaid diagrams to SVG/PNG (create, update, show, list, export, render, delete).

Top-level commands

Command	Description
suya version	Print version metadata.
suya update [--check]	Upgrade to the latest release; --check only reports availability.
suya install [--skills] [--path <p>] [--force]	Install Subaya integrations (suya-cli + planner skill bundles).
suya completion <shell>	Print shell autocompletion for the given shell.