Skip to main content

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.
The variant is recorded in 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:
If an artifact in the lockfile is no longer in the registry manifest, or its SHA-256 does not match, 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. A long sync re-signs download links that expire mid-run, the way install does, so it no longer fails with SH-NET-003 on a stale link.

CI/CD

For repeatable builds, commit synheart.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.
Set 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.

Start a project

synheart init writes .synheart/config.yaml with every setting the CLI reads from it (mock, local, receiver, ui and platform) commented out at its default, detects the app the way synheart env does, and prints what to do next: start mock data, get connection snippets, sign in, install the runtime. It needs no account and no network. Running it again leaves the file alone and exits 0. --force rewrites it and keeps the old one as config.yaml.bak, then config.yaml.bak.1, .bak.2 and so on, so a backup is never overwritten. It never writes through a symlink: a linked .synheart, config or backup path is refused with SH-CFG-007. Run it inside your app’s folder: in your home directory it refuses with SH-CFG-006, because ~/.synheart/config.yaml holds your personal settings. --json prints {created, path, project_type, next[]}.

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. Outside an app project, a missing synheart.lock is not a warning: doctor notes “Not in an app project” and suggests cd into your app or synheart init. The headline names every problem (2 warnings not signed in, no runtime), and the TRY list puts synheart login before the installs that need an account. 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 doesn’t replace a binary that a package manager (Homebrew, winget, apt, Chocolatey or go install) installed. It prints that package manager’s upgrade command instead, such as brew upgrade synheart or winget upgrade --id SynheartAI.Synheart. Pass --force to replace it anyway. 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
After other commands, the CLI prints a one-line notice on stderr when a newer version is available. It checks at most once every 24 hours. The notice does not appear with 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.