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

> Source: https://www.heyarchetype.com/docs/developers/cli

`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:

```bash title="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:

```bash title="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](/docs/developers/components).

## Sign in

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

```bash title="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](/docs/developers/components). |
| `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](/docs/developers/components).
- **`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:

```bash title="CI step"
npx archetype-os@0.3.2 pull --check
```

## Next steps

:::cards
- [Tokens in code](/docs/developers/tokens): Import the pulled tokens into your stylesheet and keep them current.
- [Component sync](/docs/developers/components): Define your components in code and push them to the brand.
- [Connect an agent](/docs/agents/connect): Give your coding agent the brand live over MCP, beside the files.
:::