# Setup and sign-in

This page covers getting the CLI installed, signing in, choosing a workspace, and keeping everything up to date. A fresh machine usually goes through them in this order: install, `init`, workspace.

## Install the CLI

If the shell can't find `sofatofu`, use the executable's absolute path when the task gives you one. Otherwise, install the CLI. You don't need to ask the user first.

Download the install script to a temporary file, then run that file. Never pipe a download straight into a shell.

- **macOS, Linux or WSL:** download `https://sofatofu.com/install.sh` and run it with `sh`.
- **Windows PowerShell:** download `https://sofatofu.com/install.ps1` and run it with PowerShell.

The script installs the latest release without prompting. If it fails, report its error message. After a successful install, run `sofatofu init` as described below.

If the shell can't find the new CLI, or finds a different copy first, use the absolute path from the script's `Installed` line for your later commands. Pass any PATH instructions from the script on to the user, and leave their shell profile alone.

If you can't run commands yourself, ask the user to download and run the script for their platform in a terminal, then run `sofatofu init`. In a terminal, `init` offers to install a coding agent if it finds none. The user can also ask a coding agent that can run commands: `Read and follow https://sofatofu.com/skills/sofatofu/SKILL.md`.

## Set up the machine

```bash
sofatofu init
```

`init` installs this skill for the agents it finds, signs in, and checks the account. Through a command tool, it installs the skill under the home folder by default. Use `sofatofu init --project` from the project directory to install it there instead. This changes the skill's install location, not the sign-in or workspace scope. You can combine it with `--agent <name>` to choose an agent.

Run through a command tool, `init` returns JSON:

- **`login: "pending"`**: share `verification_uri_complete` and `user_code` with the user once, and ask them to approve access in the browser. Keep the ask short: the link, the code and what happens next. Run `sofatofu init` again with the same flags to check whether they have. Seeing the same link again means approval is still pending. It doesn't mean the user has to approve a second time.
- **`login: "done"`**: setup is complete. If `workspace` is `null`, [select a workspace](#select-a-workspace).
- **An error**: follow its `message`. If no agent was found, run `sofatofu init --agent <name>` with your own agent's name, taken from the error message. For login errors, follow [Sign in](#sign-in), but retry with `sofatofu init` instead of `sofatofu auth login`.

When `init` finishes, ask the user to start a new agent session so the installed skill loads.

`init` sends setup data to Sofatofu, such as the setup result, the CLI version and the operating system. The [privacy page](https://sofatofu.com/privacy) describes this data. If the user doesn't want it sent, tell them to set `SOFATOFU_NO_TELEMETRY=1`.

To install only the skill, run `npx skills add https://sofatofu.com`. That doesn't install the CLI.

## Update

```bash
sofatofu update
```

`update` installs the latest CLI release using the method it was first installed with, and refreshes the installed copies of this skill. It doesn't install an agent, ask for input or sign in. Use it instead of `npx skills update`, then read the updated `SKILL.md`.

Commands may print a warning or release notice on stderr. These don't change a command's result or exit code.

- **A skill version warning:** run `sofatofu update` once, then read `SKILL.md` again. Carry on with the user's task even if the warning stays. Whether the task succeeds or fails, mention the warning in your final response and ask the user to start a new agent session. State it plainly, as [Talking to the user](../SKILL.md#talking-to-the-user) describes.
- **A newer release notice:** tell the user they can install it with `sofatofu update`.

## Sign in

```bash
sofatofu auth login
```

Use this one command both to start a login and to check whether it has been approved. Each call makes its requests and exits. It doesn't open a browser or wait for the user.

What you get back depends on where things stand:

- If a stored session works, it returns the signed-in user and workspace selection.
- If no login is pending, it returns `verification_uri_complete`, `user_code` and `expires_in` for a new approval request.
- If a login is pending, it checks approval once. When approval has gone through, it saves the session and returns the signed-in user and workspace selection.

Share each new approval link and its code with the user once, and ask them to open the link and approve access. Then run `sofatofu auth login` again to check. The user doesn't need to message you to confirm. Seeing the same link again just means approval is still pending, so check again later without asking them to approve again.

You're signed in once the command succeeds and returns the user's identity. An approval link only means it's waiting on them.

If `workspace` is `null` after you sign in, [select a workspace](#select-a-workspace). To sign in with a different account, run `sofatofu auth logout` first.

`expires_in` is how many seconds are left to approve. After that, the next `auth login` starts a new request. Share the new link only if you still need to sign in.

### When login fails

- **`access_denied`**: the user denied access. Stop, and don't start another approval request.
- **`expired_token`**: the approval code expired. If you still need to sign in, run `auth login` again for a fresh approval request.
- **`login_pending_elsewhere`**: the CLI saved an approval request for a different server from the one this command uses, and the message names that server. If the task needs the pending request's server, keep it. If the task needs the current command's server, run `auth logout` to discard the pending request and clear the stored session, then start a new login. If the task doesn't make the server clear, ask.
- **Anything else**: follow the documented recovery steps. After an unclear result, run `auth whoami` before starting another login attempt. If there's no safe recovery, or the failure keeps happening, report the blocker.

## Select a workspace

```bash
sofatofu auth whoami
```

`user.id` identifies the signed-in user. Use it for `owner` and for `change list --author`. If `workspace` is `null`, you need to select one.

When you need to match a workspace name, or none is selected, list the choices:

```bash
sofatofu workspace list
```

Check all pages before you report a workspace as unavailable.

Pick the workspace in this order: the one the user asked for, then the saved one, then the only one available. If the choice is still unclear, ask. If the requested workspace isn't available, report the blocker. Don't choose a different one.

Save a default only when the user asks for it:

```bash
sofatofu workspace use <workspace_id>
```

`workspace use` checks membership and saves the selection.

## Sign out

`sofatofu auth logout` asks the server to revoke the session, then removes the local credential and any saved approval request. It succeeds even if there was no credential. If the server can't be reached, logging out locally doesn't prove the server revoked the session.

## Uninstall the CLI

Run `sofatofu uninstall` only when the user asks you to remove Sofatofu. It signs out, removes the copies of this skill under the home folder, removes its local configuration and removes the binary. It prints the removed paths as JSON. It keeps the copies that `sofatofu init --project` wrote in a project. Delete those from the project if the user wants them gone.