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

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.
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, 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 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

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 describes.
A newer release notice: tell the user they can install it with sofatofu update.

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. 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.

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

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:

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:

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.