CLI quickstart

This takes about ten minutes. You end with a component published to Staging and showing on a page of your own.

Before you start

• Node 20 or newer, curl, and sha256sum (or shasum on macOS).
• A Taggor account on the staging portal, https://app-staging.taggor.dev/. Creating the account and approving the CLI’s sign-in are done by a person in the browser; the CLI never asks for a password.
• A hostname you control, to use as a test site (a page where you can add a script tag).

There is no npm package

During staging the CLI is one file that the staging portal serves, and the SDK it adds to your project comes from tarballs served beside it. Nothing is installed from the npm registry for Taggor itself, so the commands below run the file with node taggor.mjs.

1. Download the CLI and check its hash

Open https://app-staging.taggor.dev/cli/. The page shows one command that downloads taggor.mjs, checks its SHA-256 and stops if the check fails. The hash changes with every CLI release, so it is not copied here; take the command from that page. Run it in an empty directory:

mkdir my-components && cd my-components
# then the command from https://app-staging.taggor.dev/cli/
node taggor.mjs --version

The hash guards against a corrupted or partial download. It is served from the same host as the file, so it is not proof against a compromised host.

2. Sign in

node taggor.mjs login
node taggor.mjs whoami

login prints a code and a URL, then waits. Open the URL, check that the code matches and approve the sign-in. whoami shows your user, workspace and role. If it shows no workspace, pick one with node taggor.mjs workspaces use <workspace-slug>.

3. Create the first component

node taggor.mjs init .
npm install

init . writes a small project in the current folder and needs no network and no sign-in: taggor.json (the list of your components), package.json, tsconfig.json, and a first component in components/hello-component/src/index.tsx with its styles. Pass --component <tag> to name it; a tag needs a hyphen, for example price-table. Run init --component <tag> again in the same project to add another component. Without the . (or another folder), init keeps the project for you in ~/.taggor/projects/<tag>/ and prints its path; taggor projects list shows those folders.

npm install adds the SDK, @taggor/component, and the local check engine.

Open components/hello-component/src/index.tsx: it is one defineTaggorComponent call. What it can declare is in the component contract.

The project folder is disposable once you have published: every publish stores the source in Taggor, and node taggor.mjs pull <component> recreates the folder from the latest version (or --version, --channel).

4. Preview it

node taggor.mjs dev

This serves your components on http://127.0.0.1:4321 (change it with --port <n>) with hot reload, on a deliberately hostile test page (aggressive CSS, strict CSP) so problems show before a visitor sees them, and a playground for props and fake data. --host-html <file> previews on a page of your own.

5. Check before publishing

node taggor.mjs check

Runs the publication gates (types, size, security) on your machine, with no network. It exits with code 6 when a gate fails; each failure prints a code that has a page under build diagnostics.

6. Create a test site

node taggor.mjs sites create --name "My test site" --domain <test-hostname> --environment staging

Prints the site key and the snippet, and saves the site key in taggor.json. Use the hostname of the page where you will paste the snippet.

A site’s environment, Staging or Production, decides which version it shows: a Staging site shows the version the component’s Staging channel points to, a Production site the one its Production channel points to. Two Production sites therefore show the same version of a component; to show different versions, publish the component under another name.

7. Publish

node taggor.mjs publish

publish packs the source of each component in taggor.json, builds it remotely, creates a version, moves the Staging channel to it (the one --channel names, if you pass it) and attaches it to the site saved in taggor.json. Nothing is sent before the local checks pass, and a file that looks like a secret stops the upload. Add --dry-run to see what would be sent. Add --json to any command for machine-readable output.

8. Put the snippet on your page

node taggor.mjs sites snippet

Prints the script tag for your site. Paste it into the page, and write the component’s tag where it should appear. Install the snippet explains where it goes and what the visitor sees before the component loads, or if it never does.

What next

To do this	Run
See the versions and channels of a component	node taggor.mjs versions <component>
Move Production to a version	node taggor.mjs promote <component> --to production
Go back to the previous version	node taggor.mjs rollback <component> --channel production
Recreate a deleted project folder	node taggor.mjs pull <component>
Follow a build	node taggor.mjs logs <component> --follow
Save the privacy policy URL of a form	node taggor.mjs sites props set <component> <prop> <url> --site <site key>
List every command, or one command’s options	node taggor.mjs --help, node taggor.mjs sites props set --help

When a command fails, the message ends with the code of the error and a link to its page in API and CLI errors.