# TWG CLI — agent install & setup instructions

Use this when a user asks you to install, set up, repair, or authenticate the
Teamwork Graph CLI (`twg`).

## Agent invocation

Set `TWG_AGENT_DEFAULTS=1` for TWG commands in the agent host. If the host does
not set it, use `TWG_AGENT_DEFAULTS=1 twg <command>`. If environment assignments
are unavailable or blocked, pass `--mode agent` with explicit output
flags. Do not change host permissions to add a prefix. Agent detection records
identity only; it does not enable agent defaults. The examples below omit this
shared invocation prefix. `--mode user` explicitly overrides the opt-in.

## Rules

- **Interactive setup flow: `twg setup`.** It's rerunnable and picks the next
  missing step from local state. Do not invoke the installer-only `setup finalize`
  command directly.
- **Never ask for, echo, log, or summarize a token, and never pass one as a CLI
  flag.** Secrets are typed straight into TWG's own masked prompt (or supplied via
  env — see below).
- **Relay prompts; don't script them.** Interactive prompts read the _controlling
  terminal_ (`/dev/tty`), not stdin — so piping (`curl | bash`) is fine, and
  feeding answers on stdin (`echo yes | …`) does nothing. Keep the command in the
  foreground and pass each prompt through to the user.
- **y/N confirmations: take the shown default, but only for non-destructive
  ones.** The capitalized letter is the default (`Y/n` → yes, `y/N` → no).
  Safe to auto-accept: opening the browser for auth (that's how the URL gets
  shown, not a secret), consent-to-continue prompts, and optional add-ons like
  Bitbucket setup. If taking the default declines an optional add-on, say so
  afterward instead of letting it pass silently (e.g. "Skipped Bitbucket setup
  by default — run `twg setup bitbucket` later if you want it"). Stop and ask
  the user for anything destructive or hard to undo, like uninstall or
  force-overwriting existing config/credentials.
- **No controlling terminal (typical agent sandbox)?** You can't complete an
  interactive login, and you must not handle the token yourself. Ask the user to
  either run `twg login` in their own terminal, **or** set `TWG_TOKEN` and
  `TWG_USER` in their environment themselves (every command reads them directly —
  no login needed). Then run `twg doctor` to confirm runtime auth; do not rerun
  `twg setup`, which requires a controlling terminal.
  Don't try to fake the prompt — `twg` exits with a clear "needs an interactive
  terminal" message.

## Resolve the CLI before installing

Before reporting `twg` as missing, try its default direct-installer launcher:

- macOS/Linux: `$HOME/.local/bin/twg`
- Windows PowerShell: `$env:LOCALAPPDATA\Programs\twg\bin\twg.exe`

The rest of this document uses `twg` as shorthand. Substitute the resolved
launcher for each command. For example:

```bash
"$HOME/.local/bin/twg" setup
```

```powershell
& "$env:LOCALAPPDATA\Programs\twg\bin\twg.exe" setup
```

If bare `twg` is not found, use the resolved launcher for the whole flow and
tell the user to add its parent directory to PATH. If neither launcher exists,
install TWG. Do not treat auth or command errors as PATH failures.

## Install

If `twg` or the fallback launcher works, run `twg setup` through that resolved
executable. Install only when neither launcher is available:

**macOS / Linux**

```bash
curl -fsSL https://teamwork-graph.atlassian.com/cli/install | bash
```

**Windows PowerShell**

```powershell
curl.exe -fsSL https://teamwork-graph.atlassian.com/cli/install.ps1 -o "$env:TEMP\twg-install.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\twg-install.ps1"
```

## Run setup

Run `twg setup` through the resolved executable in the foreground and relay
each prompt. You'll only ever be asked for:

- **Consent** — show it, ask yes/no.
- **Email / site** — provide if asked, or pre-seed: `twg setup --user you@example.com --site hello`.
- **Token** — TWG prints a URL and asks to open the browser. The user can open the URL, consent to relevant scopes and grant access to the CLI.
- **Bitbucket (optional)** — after core setup + doctor, TWG may offer it. Yes/no;
  setup succeeds either way. Set up later with `twg setup bitbucket`.

## Verify

Run `twg doctor` through the same resolved executable; use bare `twg` only
when it resolves on PATH. If it is not found, keep using the resolved executable
and tell the user to add its parent directory to PATH.

Report: binary path, skills status, auth status, selected site, Bitbucket status
(if shown), and the doctor result. Never include token values.

## Repair / upgrade / uninstall

- **Repair** — rerun `twg setup` (re-pass `--user`/`--site` if known).
- **Upgrade** — `twg upgrade && twg setup --force-auth && twg doctor`.
- **Beta** — `twg upgrade --channel beta --yes && twg doctor`.
- **Uninstall** — `twg uninstall --dry-run` to preview, then `twg uninstall`
  (removes the CLI, scheduled upkeep, installer-owned skills, credentials, and
  local TWG configs).