Sign in
synheart login prints a URL and a code, opens your browser (unless you pass --no-browser) and waits while you approve it. The CLI stores your tokens in the system keychain, or in ~/.synheart/credentials.enc when no keychain is available. Commands that call the network (install, sync, org, usage) need a session. Commands that only touch your machine (mock, local, receiver, doctor, version) do not.
synheart whoami, synheart usage and the TUI refresh your plan and organization claims automatically when your sign-in is more than 5 minutes old, so an upgrade shows up without signing in again. synheart auth refresh forces a refresh if you ever need one.
If a command fails with an SH-AUTH-* code, run synheart auth status. It checks the credentials file, the keyring and the token expiry, and tells you which step failed. See Errors and environment for each code.
Install the runtime
The CLI manages the runtime artifact. You install the SDK packages themselves with your platform’s package manager (pub.dev, Maven Central or Swift Package Manager).synheart install downloads artifacts from the Artifact Registry into your project’s synheart/vendor/ directory and records them in synheart.lock. The core runtime goes to synheart/vendor/runtime/, and every other package goes to synheart/vendor/<package>/.
Products are syni and core. Components are runtime and spec. Give one name to install everything it covers, or two to pin one package:
Channel, version and platform
Runtime variants
The runtime ships in three variants:
Without
--variant, the server picks the variant your plan includes. Pass --variant edge|stable|lab to ask for one. If your account is not entitled to it, the install fails with SH-INST-FORBIDDEN.
synheart.lock, so synheart sync and synheart runtime upgrade stay on it.
Inspect, upgrade or install from a local build
runtime current exits 1 with SH-RT-NOLOCK when the project has no lockfile. runtime install --from copies a runtime you built yourself into synheart/vendor/runtime/, with no login or network.
synheart.lock
synheart install writes synheart.lock in your project. It pins the exact version, variant and artifact hashes that were resolved. Commit it.
synheart sync reads the lockfile and installs exactly what it pins, with no new resolution:
sync stops with SH-INST-004 or SH-INST-005 instead of installing something different. synheart doctor also checks that the vendored files still match the lockfile.
CI/CD
For repeatable builds, commitsynheart.lock and run synheart sync in CI. Sign in with a CI token, because the browser flow needs a person. Create the token in the dashboard and store it as a secret.
SYNHEART_CI_TOKEN in the environment. Passing --ci-token also works, but a flag is visible in process lists and shell history. Add synheart update --check if you want CI to flag a new CLI release: it exits 1 when one is available.
Diagnose your setup
synheart doctor reports each step as ok, warn or error. It exits 1 only when your app cannot work: the runtime is missing or incompatible, its files are missing or modified, or a library lacks functions its variant needs. Anything else, such as a busy port, an available update or being signed out, is reported without changing the exit code. Use --port to check a different port and --project to inspect another project.
synheart env reads only local state. It prints the Go version, OS, cache and config paths, the lockfile and vendor directory, the project type (ios, android, flutter, multi or none), app IDs, the signed-in account and the pinned runtime.
Update the CLI
synheart upgrade is an alias. The CLI reads the release manifest from https://dist.synheart.ai/synheart-cli/latest/manifest.json, downloads the archive for your platform, verifies its SHA-256 against the manifest and swaps the binary in place. It saves the previous binary to ~/.synheart/bin/synheart.prev, which --rollback restores.
synheart update refuses to run when a package manager (Homebrew, apt, Chocolatey or go install) manages the binary. Update with that package manager, or pass --force. On Windows, run the installer again. The installer scripts are also the way to recover a broken install:
- macOS and Linux:
curl -fsSL https://synheart.sh/install | bash - Windows (PowerShell):
iwr -useb https://synheart.sh/install.ps1 | iex
SYNHEART_NO_UPDATE_CHECK=1, in CI, in agent mode or with --json. It is also skipped for update, doctor, mcp and completion.
If an update fails, you get SH-UPD-APPLY (the existing binary is left untouched) or SH-NET-002 (the manifest could not be fetched). Both are safe to retry.