Skip to content
Taggor docs

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

Section titled “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).

1. Download the CLI and check its hash

Section titled “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:

Terminal window
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

Section titled “2. Sign in”
Terminal window
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

Section titled “3. Create the first component”
Terminal window
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

Section titled “4. Preview it”
Terminal window
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

Section titled “5. Check before publishing”
Terminal window
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

Section titled “6. Create a test site”
Terminal window
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

Section titled “7. Publish”
Terminal window
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

Section titled “8. Put the snippet on your page”
Terminal window
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

Section titled “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.