# Set up Surething

You are a coding agent reading this because a person asked you to set up
Surething — a platform that gives you hands in their world: their projects,
pages, websites and scheduled routines, and every third-party app they have
connected (Gmail, Slack, Notion, Google Calendar, LinkedIn, …).

Three steps, safe to re-run:

## 1. Install

```sh
npm install -g @surething/headless --@surething:registry=https://sandbox-registry.surething.io
```

One install, three commands on PATH: `surething`, `surething-page`,
`surething-website` — the page and website CLIs ride along as dependencies.

(Node 22+. The scope-registry flag is required while the CLI is in private
preview — a plain `--registry=` would send public packages like `commander` to
the private registry, which only serves the @surething scope, and 404.)

## 2. Set up

```sh
surething setup
```

The CLI talks to `https://surething.io` by default. Only if you fetched this
document from some other host, add `--api-url <scheme + host it came from>`;
on a local dev stack the API is a separate port — the person will tell you
which.

This signs the machine in and teaches every coding agent on it (Claude Code,
Codex) the full CLI surface by installing skills into `~/.claude/skills` and
`~/.codex/skills`.

A browser window opens during sign-in. **Tell the person to approve the login
in that browser window** — the command waits and finishes on its own. If no
browser opened, give them the URL and code the command printed.

## 3. Verify

```sh
surething whoami
surething tools search "calendar"
```

The first answers who is signed in; the second shows the connected apps you
can now call on their behalf.

## From here

The skills installed in step 2 are the real reference — your next session
knows them natively. In this session, read
`~/.claude/skills/surething/SKILL.md` (or `~/.codex/skills/surething/SKILL.md`)
for what each command does, and `surething --help` for the surface.

If a command answers 403, the credential was revoked — run `surething login`.
Nothing here spends the person's money except `surething tools exec`, which
runs real actions on their connected accounts and bills their Surething wallet;
their wallet is the cap.