# Set up Torque Lift for this repo

This page is for your coding agent. Paste this into your agent, with your setup code:

> Follow the instructions at https://torquelift.ai/cli/setup.md to set up Torque Lift for this
> repo. My setup code is TL-XXXXX-XXXXX-XXXXX-XXXXX.

You can also run the command yourself, in your terminal: `npx https://torquelift.ai/cli/torque-lift.tgz`
asks each question as it goes. The steps below are the same run, for an agent that can't type
answers.

## Rules

- Run only the command below. Don't edit files in the repo, run its scripts or package manager, or
  merge, approve or push anything. Torque Lift opens pull requests later, and a person on your team
  merges each one.
- Ask the person for nothing but these: the setup code, their company's AWS account ID, the
  GitHub login that signs in to the console, and a yes once the GitHub App is installed. Past events
  from another analytics tool are optional and come later: don't ask about them unless the person
  raises it. Never ask for AWS
  access keys, passwords or GitHub tokens, and never print the setup code or the token file
  (`~/.config/torque-lift/setup.json`) anywhere else.
- Don't guess an answer for the person. If the command says it needs one, ask them.

## Before you start

Tell the person what they need to have ready, before you run anything: their setup code (it
starts with `TL-`), their company's 12-digit AWS account ID, someone with admin rights in that
account for one click, and permission to install a GitHub App on the repo.

- Node.js 20 or newer (`node --version`).
- The terminal is in the app's git repo. In a monorepo it finds a web app (Next.js, Remix or React
  Router, or React with Vite) in a folder of the repo, `apps/` or `packages/` (and asks which when there are several; with `--no-input` it
  stops with exit 4 until you add `--app-path <folder>`).
- An AWS CLI session for the company's AWS account is useful but not required. The command
  checks the new stack's status with it, read-only, when there is one. Nothing is ever pasted
  back: Torque Lift works out the stack's bucket and roles itself.

## Run it

Keep the setup code in the environment, not on the command line:

```
TORQUE_LIFT_SETUP_CODE=TL-XXXXX-XXXXX-XXXXX-XXXXX npx -y https://torquelift.ai/cli/torque-lift.tgz --no-input --no-open
```

`--no-input` means it never asks or waits: it does what it can, then stops and says what comes
next. Each step is checked against Torque Lift's record, so running it again carries on where it
stopped. After the first run the setup code is no longer needed (it is used once; the command keeps
a token for this machine).

If the command prints a line starting with "!" about the default branch's ruleset, show it to the
person as it is: Torque Lift opens pull requests only where a ruleset requires a pull request with
an approval, and they can add one in GitHub while setup goes on. It does not stop the command.

If it prints a line starting with "! An organization policy", "! Torque Lift's stack can only be
created in us-east-1" or "! An organization policy stops this account", show it to the person as it
is: their AWS session can't create the stack, and the line says who to ask (whoever manages their
AWS organization). It does not stop the command, but the stack will fail until it is fixed.
`npx -y https://torquelift.ai/cli/torque-lift.tgz check-aws --json` asks again, read-only, with
every finding, once they say it is fixed. Never run anything else in AWS for them.

If the person's AWS admin is someone else, the output names a page to send them (`Not an AWS admin?`):
send that page's address, and nothing else.

Read the exit code and the last lines it printed:

| Exit | Meaning | What to do |
|---|---|---|
| 0 | Set up | Tell the person: Torque Lift opens a pull request in their repo, “Torque Lift: review your tracking plan”, and merging it is their growth lead's approval of the plan (it is approved in GitHub, not in the console). They can sign in to the console with GitHub as the login they named; if it asks which company, they pick the one the command names. Stop. |
| 4 | Needs an answer | Ask the person the one question it names, then run it again with the flag it names added to the flags you already have: `--aws-account <12 digits>`, `--history <posthog\|mixpanel\|segment\|amplitude\|none>`, `--console-login <github login>`, `--app-installed`. |
| 3 | Waiting on someone else | Torque Lift's side, or the AWS stack. Show the person what it printed (a link, if there is one), say who it waits on, and offer to run it again later. If it says "Setup is not finished yet: your part is done", tell the person plainly that their part is done and setup is not complete: Torque Lift is connecting the account, nothing more is needed from them, and running the command again says "Torque Lift is set up" when it is. |
| 1 | A step failed | Show the person the message. Don't retry in a loop. |
| 2 | Bad arguments | Fix the command and run it again. |

Past events are optional and not part of setup (setup is complete without them). If the person wants
them, they run `torque-lift history` themselves, which asks which tool they come from. For Mixpanel
(or Amplitude's Export API) it takes a secret. **Never run it, and never ask for the
secret or take it in any form:** tell the person to run `npx -y https://torquelift.ai/cli/torque-lift.tgz history`
in their own terminal, where they type the project and secret. It refuses to run for an agent (exit 4).

One question is the person's own: **which GitHub login signs in to the console.** Ask who on the
team should see it (their own login is the usual answer; comma-separate to name more than one,
up to 5). The command only records the name. Torque Lift turns it into console access when it
finishes onboarding, at https://console.torquelift.ai, with the GitHub sign-in.

Two steps need a person's own hands. Give them the link the command printed:

- **The AWS stack, first.** As soon as the AWS account ID is in, the command prints the stack link
  (once Torque Lift has made it, which can be a moment later: run it again if it says so).
  Someone with admin rights in the company's AWS account opens the link, ticks the IAM box and
  clicks Create stack. The stack holds your event bucket and the roles Torque Lift uses, all in
  your account. It builds in the background while the person does the GitHub App and the
  questions. About two minutes after Create stack, run the command again: it sees the stack
  finished, on its own or through Torque Lift, and goes on. Never ask the person to copy anything
  from the AWS console back.
- **The GitHub App.** If the person can't install it (an owner of the GitHub organisation must), the
  exit 4 message names a page to send to an owner: give it to the person as it is, and run again with
  `--app-installed` once the owner says it is installed. Otherwise open the link and install Torque Lift on this repo only (the link has the
  repo already picked where it could be found: the person still checks it and clicks Install).
  Once the person says it is installed, run again with `--app-installed`.
- **The GitHub sign-in.** Once the App is installed, the command may print a short code and
  `https://github.com/login/device`: give both to the person as they are. They open the page and
  type the code on github.com themselves, signed in as someone who can push to the repo; the
  command waits and carries on by itself. Never type the code, open the page for them or ask for
  their GitHub password or a token. If it stops saying the account can't push to the repo, someone
  who can must do the sign-in.

## Another repo (an Android or iOS app, or a second web app)

A company's apps are often in more than one repo. Once the first repo is set up (above), ask
Torque Lift for a new setup code and run the command in the other repo with `--add-repo`:

```
TORQUE_LIFT_SETUP_CODE=TL-XXXXX-XXXXX-XXXXX-XXXXX npx -y https://torquelift.ai/cli/torque-lift.tgz --add-repo --no-input --no-open
```

It checks the repo (Android with Kotlin and Gradle, or iOS with Swift and an Xcode project), tells
Torque Lift about it and asks for nothing about AWS or past events: those are the company's, and
already given. If the app is in a folder, add `--app-path <folder>`; for Android it finds an `app`
module and for iOS a single folder with an `.xcodeproj` by itself. Same exit codes as above:

- **4, needs an answer.** The GitHub App has to reach this repo too: open the link it prints, add
  the repo under Repository access (selected repositories only), then run it again with
  `--app-installed`.
- **1, "isn't a stack Torque Lift supports yet".** It names the checks that failed (a committed
  Gradle wrapper, unit tests, CI on pull requests, a Swift Package Manager project). Show the
  person and stop.
- **0, added.** Torque Lift connects the repo on its next onboarding run, then opens the first
  pull request in it for the person's team to review. Nothing else to do.

Torque Lift also checks where the app starts (the Android `Application` class, the iOS entry
point) before it opens any pull request.

## If it fails

- **"This app isn't a stack Torque Lift supports yet" (exit 1).** Torque Lift works today on
  Next.js 14 or newer (the App Router or the Pages Router), Remix 2 or React Router 7 (framework mode)
  on Vite, or React with Vite 5 or newer, TypeScript, a lockfile, Vitest or Jest (Vitest on anything
  built by Vite), and CI on pull requests. A Pages Router app's `pages/_app` and a Vite app's entry
  file must wrap what they render in an element on lines of its own (`<>...</>` will do), so the
  provider can go beside it; a Remix or React Router app's `app/root` must open `<body>` on a line of
  its own. The check says so when one does not. The command has told Torque Lift which stack this is. Tell the person which check
  failed and stop.
- **"That setup code didn't work", or "no longer works" (exit 1).** The code is used once and lasts
  seven days. Ask the person to get a new one from Torque Lift.
- **Node is older than 20.** Ask the person to update it, or to run the command where Node 20+ is
  installed.
- **Anything else.** Stop and give the person the command's full output.
