Developers

The CLI

Install archetype-os, sign in, and use every command and flag to pull your brand into a repository and push components back.

archetype-os keeps a repository and a brand in step. It pulls the brand into an archetype/ folder your build imports and your agents read, and sends the components your code defines back to Archetype.

Install

The CLI is the archetype-os package on npm, currently version 0.3.2. It needs Node 20 or later. Run it with npx from the root of your repository:

Terminal

npx archetype-os init --url https://www.heyarchetype.com --brand <brand-slug>

Settings → Agents, on the Repository tab, gives you this line with your brand filled in: choose Do it by hand instead. Or copy the setup prompt there and let your coding agent run it.

For CI, and for anyone who wants the same code on every run, pin an exact version as a dev dependency rather than running whatever is latest:

Terminal

npm i -D archetype-os@0.3.2

pull and status need nothing else. components push also needs esbuild, playwright-core and a Chrome; see Component sync.

init signs you in the first time. To sign in on its own, run login:

Terminal

npx archetype-os login

It opens your browser on Archetype's approval screen, the same one an MCP client uses, and waits up to 10 minutes for you to approve. The connection is read-only, which is all pull needs, and it shows up under My connections in Settings → Agents as Archetype CLI.

login --write asks for edits too (the Change the brand when you ask it to box). components push needs this when you run it yourself.
--no-browser prints the sign-in link instead of opening it. This is how an agent signs in for you from a shell with no terminal: it runs the command and passes you the link.

In CI there is no one to sign in, so set ARCHETYPE_TOKEN to an API key instead. An admin creates one in Settings → Agents, on the API tab, with Create API key. For components push in CI, tick Sync components from code when you create it.

Commands

Command	What it does
`init`	Connects this project to a brand and pulls it in: signs in, saves `archetype.json`, pulls into `archetype/`, and points `AGENTS.md` at the brand's rules. Safe to run again.
`pull`	Updates `archetype/` to match the brand. Writes only the files that changed and removes what the brand no longer has.
`pull --check`	Changes nothing. Exits with 1 if `archetype/` is behind the brand.
`status`	Shows the brand, the address, how you are signed in, and whether `archetype/` is current.
`components push`	Draws the components your `*.archetype.tsx` files define and sends them to the brand. See Component sync.
`login`	Signs in through the browser.
`logout`	Forgets this project's sign-in.

Flags

Flag	Works with	What it does
`--url <address>`	any	Your Archetype address. Overrides `archetype.json`.
`--brand <slug>`	any	The brand. Overrides `archetype.json`.
`--check`	`pull`	Change nothing; exit 1 if `archetype/` is behind the brand.
`--no-browser`	`init`, `login`	Print the sign-in link instead of opening it.
`--write`	`login`	Also allow edits.
`--all`	`logout`	Forget every sign-in, not just this project's.
`--dry-run`	`components push`	Say what would change in the brand, change nothing.
`--out <file>`	`components push`	Write what would be sent to a file instead of sending it. Needs no sign-in.
`--only <keys>`	`components push`	Only these components, comma-separated keys.
`--keep`	`components push`	Keep components this repository synced before but no longer defines. They are removed otherwise.
`-h`, `--help`	any	Show the help.
`-v`, `--version`	any	Show the version.

Environment variables

Variable	What it does
`ARCHETYPE_TOKEN`	An API key to use instead of a browser sign-in. The way to run in CI.
`ARCHETYPE_URL`	The Archetype address, like `--url`.
`ARCHETYPE_BRAND`	The brand slug, like `--brand`.
`ARCHETYPE_CONFIG_DIR`	Where to keep sign-ins, instead of the default folder below.
`ARCHETYPE_CHROME`	The Chrome binary `components push` draws with.

A command reads the address and brand from its flags first, then the environment, then archetype.json. That order lets CI override a committed config.

Files it writes

archetype.json, at the project root: the address and brand. Commit it. Every command looks for the nearest one at or above the folder you run it in, up to the repository root. It can also hold a components block for components push; see Component sync.
archetype/, beside it: the brand as files. The CLI owns this folder, so don't edit it by hand: the next pull overwrites it. Commit it, and the diff of each pull is the record of what changed in the brand.
AGENTS.md: init adds one line pointing at archetype/AGENTS.md, or creates the file with it. If you have a CLAUDE.md, it adds @AGENTS.md at the top so Claude Code reads the same rules.
Sign-ins, never in the project: ~/.config/archetype-os/credentials.json (or under XDG_CONFIG_HOME), or %APPDATA%\archetype-os on Windows, readable by you alone.

logout removes the sign-in from that file. The connection stays listed in Settings → Agents until it expires or you revoke it there.

Exit codes

Code	Meaning
`0`	Done.
`1`	It ran, and the answer is no: `archetype/` is behind, or a request failed.
`2`	It couldn't run as asked: a missing config, a missing sign-in, or a bad flag.

In CI

Two ready-made GitHub Actions workflows live on your Archetype address. Both read the archetype.json that init wrote, so commit it first, and both need the repository secret ARCHETYPE_TOKEN.

/ci/archetype-pull.yml pulls the brand every weekday at 06:00 UTC (and from a button under Actions) and opens a pull request when it changed. Turn on Allow GitHub Actions to create and approve pull requests under the repository's Settings → Actions → General.
/ci/archetype-components.yml runs components push on every push to main that touches a *.archetype.* file, components/, app/, src/, a stylesheet or archetype.json.

To fail a pull request when the folder is out of date:

CI step

npx archetype-os@0.3.2 pull --check

Next steps

Tokens in codeImport the pulled tokens into your stylesheet and keep them current.Component syncDefine your components in code and push them to the brand.Connect an agentGive your coding agent the brand live over MCP, beside the files.

Something missing or wrong on this page? Write to support@heyarchetype.com.