The Startup OS CLI onboards a product end to end, checks that it is wired correctly, and moves its Instance to new platform releases. It installs as startup-os, and as the shorter sos.
Install
You need Node 24 or later, git, and the GitHub CLI signed in to github.com with gh auth login. Your GitHub account must be an owner or admin of the organization, and able to edit private repositories, workflows, and Actions secrets.
Sign in to the dashboard and download the CLI from /api/cli/download. The file is named for the platform release it carries. Then install the file you downloaded:
npm install -g ./startup-os-cli-v<release>.tgz
You do not need access to the platform’s private repositories, a GitHub Packages token, or a Cloudflare account. If the download is unavailable, the release has not been published yet.
sos --version prints the platform release the CLI carries. The CLI has no version of its own.
Everyday commands
| Command | Does |
|---|---|
sos status [owner/repo] |
Checks whether a product is wired correctly. Read-only, and safe to run anywhere. |
sos onboard [owner/repo] |
Onboards a product end to end. Interactive. |
sos adopt [owner/repo] |
Moves the product’s Instance to the CLI’s platform release, as a pull request. |
sos connect [owner/repo] |
Connects integrations such as billing, analytics, and email. Interactive. |
owner/repo is the product’s repository, not operations. Inside a checkout you can leave it out: the CLI reads the repository from the git remote, or from STARTUP-OS.yaml inside an Instance, and says which one it chose. An argument you pass always wins.
Flags
| Flag | Does |
|---|---|
--check |
Shows what would happen and changes nothing. With onboard, it needs an explicit owner/repo and never asks a question. |
--only <phase> |
Runs one onboarding phase, to repair it. An unknown name lists the valid ones. |
--yes |
Accepts every default without asking. A step that has no default still fails, so this never answers a question that is yours. |
onboard and connect need a terminal to ask questions in. Without one, and without --check, they stop before doing anything. That is why a coding agent previews with --check and hands the real run back to you.
Onboarding phases
sos onboard works in eighteen phases. It keeps no state file: each run looks at what is already true and does only what is missing, so an interrupted run costs nothing. Run it again to carry on.
| Phase | Checks and does | Needs you |
|---|---|---|
preflight |
The GitHub CLI is installed and signed in, and you are an admin of the organization | |
scaffold |
Creates <org>/operations in one push. Never overwrites an existing Instance. |
|
facts |
Your stage, customers, objective, and the one thing Startup OS must never do without asking | Answers |
channels |
Where the product speaks, and how often | Answers |
content |
Records content topics, feature-based writing and founder voice configuration | Answers where needed |
features |
Inspects shipped feature inventory | Review missing facts |
changelog |
Reports the historical changelog audit handoff | Review the audit |
storage |
Creates the bucket for media the product publishes | Your storage provider’s CLI, or its console |
gtm |
Reports the source-inspected GTM assessment and unresolved questions | Review proposed strategy |
growth |
Configures journey, creative and growth inputs while preserving existing answers | Answers and approvals where needed |
credentials |
Stores the Instance’s repository secrets, including your own model credential, each checked against the live API first | Secrets, typed on hidden input |
labels |
Creates the labels the loop files issues with | |
schedules |
Turns on the credential audit | |
app |
Checks the Startup OS GitHub App is installed on the Instance and your product’s repository | Installing it in your browser |
reviewer |
Installs the pull request reviewer in your product’s repository | A secret and a variable in that repository |
registry |
Registers the Instance with the Startup OS GitHub App, which checks you are an organization admin and that it can reach the repositories | |
routines |
Sets up tasks that run on your machine, for products that publish locally | The path to your Instance checkout |
verify |
Validates the Instance and runs the credential audit end to end |
A phase that waits on you, such as installing the app, ends the run cleanly and tells you to run the command again once you have done it.
Keeping an Instance current
sos adopt replaces the Instance’s generated files, such as workflows and routines, with the ones from the CLI’s platform release. It leaves the files that are yours alone, schedule included, regenerates credential settings from your Instance’s own declaration, reports new configuration keys rather than merging them into yours, validates the result, and opens a pull request for you to merge.
Releases also open adoption pull requests on their own. See The Operations Instance.
Other commands
| Command | Does |
|---|---|
startup-os product inspect [dir] |
Summarizes a manifest, its evidence, and its compatibility |
startup-os product validate [dir] |
Validates a manifest and its artifacts |
startup-os artifact validate <path> |
Validates one artifact against its schema |
startup-os compatibility check [dir] |
Checks a manifest’s compatibility range against the CLI’s platform release |
startup-os skills list [--domain <d>] |
Lists the skills in the registry |
Exit codes
| Code | Means |
|---|---|
0 |
Passed, or waiting on you |
1 |
Findings, or a phase failed |
2 |
The command could not run: a missing argument, no terminal, or an unknown command |
GTM and experiment review
| Command | Does |
|---|---|
startup-os product onboard owner/app --only gtm --check |
Reports the inspected GTM assessment and open questions without adoption. |
startup-os product gtm-propose DIR --assessment PATH --check |
Validates an assessment and candidate strategy; omit --check to prepare local review files. |
startup-os product experiment-propose DIR --previous PATH --candidate PATH --decision PATH --at DATETIME --check |
Checks a retained transition; omit --check to prepare its local review and snapshot. |
startup-os product experiment-status DIR --experiment PATH |
Derives current running admission or review-needed. |
startup-os product review-propose DIR --candidate PATH --review PATH --outcome ID --check |
Checks a complete weekly or quarterly review bundle; omit --check to prepare it locally. |
startup-os product review-status DIR --proposal PATH |
Checks whether the complete bundle reached the canonical branch; --record records proven adoption. |
PATH, DIR, ID and DATETIME are placeholders for real files, identifiers and an explicit timestamp. Preparation does not accept strategy, register or start a test, push, merge, send, publish or spend. experiment-status is a check, not an execution command. Review and promote complete state through the existing Git path, then recheck current authority before effects. See Go-to-market workflow.