Install Rovito and sign in to Bitbucket

This guide takes you from installation to reading your first pull request. You need a Bitbucket account with access to a repository. Browser sign-in is built in. You don't need Go, Docker, an API token, or an OAuth app to get started.

Using another operating system? Jump to Linux or Windows. Already installed? Start with sign-in.

Install on your Mac

Download the Mac installer, open the package, and follow the prompts. It works on Apple Silicon and Intel Macs. macOS may ask for your administrator password.

The package is signed and notarized. You don't need to check a checksum or move the executable yourself. Rovito is a command-line tool, so it installs in /usr/local/bin/rovito, not Applications.

Install from Terminal instead
curl --fail --silent --show-error --proto '=https' https://rovito.scubapig.software/downloads/v0.1.295/install.sh | sh

The command installs the same package and checks the download and Apple approval automatically.

Open a new Terminal window and check that Rovito is available:

rovito version

You should see version 0.1.295. Next, sign in below.

Sign in to Bitbucket

Already signed in? Run rovito auth list to see your saved logins, called profiles. Use rovito auth switch NAME to select one, then skip to the connection check below. You do not need another login for another repository.

OAuth works out of the box. To sign in with your Bitbucket account, run:

rovito login

Use the arrow keys to choose Everyday development for reviews, merges, repository writes and Pipelines. Review and comment, Read only, and Administration are also available. Give the profile a name you recognize, such as work; that name is not required.

Authorize Rovito in your browser using the Bitbucket account that can access your repository. Keep Terminal open until login finishes. Rovito shows the Bitbucket account name and ID separately from your chosen profile name. Your profile becomes active, and credentials stay in your operating system's keyring.

Rovito never asks for or receives your Bitbucket password. Sign-in happens in your browser with Atlassian or your company's sign-in provider. Rovito handles the OAuth setup for you.

How is my login protected?

Your tokens are stored in your operating system's credential vault: Keychain on Mac, Secret Service on Linux, or Credential Manager on Windows. A locked or unavailable vault stops sign-in rather than saving tokens in a plain-text file.

Rovito's HTTPS login service exchanges and refreshes tokens in memory; it does not store user tokens in its database. Requests to Bitbucket go from the CLI to Bitbucket, not through the login service. Your Bitbucket permissions still apply, and the access level you choose limits what Rovito will do.

I want to use an API token

You need your Atlassian account email and a Bitbucket API token with scopes. Follow the token instructions to create one with the permissions your work needs.

rovito login --type api-token

Enter the token only at the hidden prompt, not in the command or an agent conversation. This is not an app password or OAuth consumer secret.

Check the connection

rovito auth doctor

Doctor checks the active login and reports what needs attention. Add --profile NAME to check another. The saved-login list and picker show the last recorded account name; doctor checks it again. Matching names have distinct account IDs, and an unavailable name does not prevent a valid login from working. A healthy login is not proof of access to every repository; try your repository below.

Read your first pull request

Use the workspace and repository names from your Bitbucket URL. For example, https://bitbucket.org/acme/service/ becomes acme/service. Replace your-workspace/your-repo below:

rovito pr list --repo your-workspace/your-repo

Choose a PR from the list and replace 42 with its number:

rovito pr view 42 --repo your-workspace/your-repo

An empty list just means there are no open pull requests. You can still check your Pipelines.

Next, connect your coding agent or comment, review, merge and run builds in Terminal.

Use multiple accounts and workspaces

You can keep work and personal accounts signed in at the same time. Give each a different saved-login name; only the default for terminal commands changes. To add another account, run:

rovito login --name personal

Use a new name rather than replacing an existing login. In the browser, choose the intended Bitbucket account. If the browser keeps using your work account, switch accounts there before authorizing. Check the account name and ID that Rovito shows when login finishes.

To choose a saved login for your terminal, run rovito auth switch. To use one for a single command without changing that default:

rovito pr list --profile personal --repo your-workspace/your-repo

Remember a login for a repository

Inside your checkout, run rovito context use. Check the suggested repository and choose its login. Rovito remembers that choice across this repository's checkouts on this computer, without changing your global default or Bitbucket permissions. This needs a version whose context --help lists use.

rovito context use work --repo your-workspace/your-repo
rovito context show --repo your-workspace/your-repo

context show explains the effective login and its source. --profile overrides ROVITO_PROFILE, which overrides the remembered login, then your global default. A remembered repository may be used for writes too; normal confirmation and commit checks still apply.

Run rovito context list to see your choices, or rovito context forget --repo your-workspace/your-repo to remove one without signing out. If its login is missing or changed, Rovito stops instead of silently trying another account. Sign in again with the same name and account, choose another login, or forget the choice.

The CLI account guide covers scripts, environment overrides, renamed repositories and recovery. The older context bind command sets one default repository for a login; it does not choose a login for each repository.

More than one workspace

One OAuth login works across the workspaces that its Bitbucket account and granted permissions can access. You do not add workspaces one by one, and login has no workspace-selection menu. Name the repository as workspace/repository when running a command.

For an agent, create a connection for each account. Choose Repositories this login can access to work across its workspaces, or restrict a connection to one repository. There is no selected-workspaces restriction yet.

Understand and change permissions

Bitbucket decides what your account and token can access. Your Rovito login can restrict which actions it uses. An agent connection separately selects which tools it exposes. Allowing an action in one place does not grant it in the others.

Check saved login permissions with rovito auth list. To change them, sign in again using the same login method and profile name:

  • Rovito's hosted browser login: rovito login --name NAME.
  • API token: rovito login --type api-token --name NAME. Enter a token with the required Bitbucket scopes when prompted.

For any existing login configured another way, follow its original sign-in instructions; do not change its server or method as a permission workaround. Choose the access you need and confirm the change. A separate profile name keeps the old login. For an agent, also update its saved configuration. Do not choose Administration just to work around an unexplained error.

Download and run on Linux

Version 0.1.295, built from source commit 6b0966f7c467c518de8b5bf6c84f33250dafb262. These archives contain the current CLI commands.

Use a desktop session with an unlocked Secret Service keyring, such as GNOME Keyring, for stored browser login. A minimal server or container may not have one. Existing environment credentials are a CLI route; current v2 MCP requires stored credentials and rejects environment overrides. Native Grok Bot and OpenAI dot setup has not yet been verified.

Start in a directory where you want to keep Rovito, then paste this block into a Bash or Zsh terminal. It selects x86-64 or ARM64, downloads over HTTPS, verifies the displayed SHA-256 and runs the new executable. It needs curl, sha256sum and tar. It creates a new versioned directory and leaves your existing binary, PATH, shell files and login unchanged. These Linux archives have no publisher signature.

(
  set -eu
  directory="not created"
  stage="checking prerequisites"
  trap 'rovito_download_status=$?; if [ "$rovito_download_status" -ne 0 ]; then printf "Linux setup failed at %s. Directory: %s\n" "$stage" "$directory" >&2; fi; exit "$rovito_download_status"' EXIT
  [ "$(uname -s)" = Linux ] || { echo "These instructions are for Linux." >&2; exit 1; }
  for tool in curl sha256sum tar; do command -v "$tool" >/dev/null || { echo "Required tool is missing: $tool" >&2; exit 1; }; done
  case "$(uname -m)" in
    x86_64) arch=amd64; expected=8f5b480259e662ef9ac8e267064758c8651cd6de32c222e8fe58a98236b536ed ;;
    aarch64|arm64) arch=arm64; expected=5f6a97bda55566e474154f67766c52dc44aaed3c4eec66f23ba8c67e653752b8 ;;
    *) echo "This download supports x86-64 and ARM64 Linux." >&2; exit 1 ;;
  esac
  directory="$(pwd -P)/rovito_0.1.295_$arch"
  stage="creating a fresh directory; existing paths are preserved"
  mkdir -- "$directory"
  archive="$directory/rovito.tar.gz"
  stage="downloading the archive"
  base=https://rovito.scubapig.software/downloads/v0.1.295
  curl --fail --show-error --location --proto '=https' --proto-redir '=https' --connect-timeout 20 --max-time 120 \
    "$base/rovito_0.1.295_linux_$arch.tar.gz" --output "$archive"
  stage="checking the download hash"
  printf '%s  %s\n' "$expected" "$archive" | sha256sum --strict --check -
  stage="extracting the verified archive"
  tar -xzf "$archive" -C "$directory" --no-same-owner
  rm -- "$archive"
  stage="running the selected Linux executable"
  "$directory/rovito" version --output json
  printf 'Use this executable for your next command: %s/rovito\n' "$directory"
)

Success prints the version information and absolute executable path. Replace /absolute/path/printed/rovito below with that path, and replace the repository name:

"/absolute/path/printed/rovito" login
"/absolute/path/printed/rovito" pr list --repo your-workspace/your-repo

Choose the access you need during login, then use the current sign-in, agent and everyday-workflow guides. Use the printed absolute executable path in place of rovito in those examples.

The download or version check failed

The command reports its failed stage and directory. For a missing download or network failure, check the URL and connection and reopen Downloads. For a checksum mismatch, stop without running the archive. For an unsupported CPU or an executable error, check that this is Linux on x86-64 or ARM64. Do not bypass verification.

An existing directory or symlink is preserved and stops the command before downloading. Choose a new empty working directory for another attempt. Inspect any directory created by a failed attempt before removing it; do not delete or overwrite an existing installation. A new version can run in its own directory while the old one remains available.

Windows

Install the Windows archive

Windows still uses the older archive download. Native Windows installation has not yet been validated.

In a new folder, run the download commands for your processor. Compare the two displayed hashes and stop if they differ.

Windows · x86-64

$base = 'https://rovito.scubapig.software/downloads/v0.1.0-pilot.2'
$artifact = 'rovito_0.1.0-pilot.2_windows_amd64.zip'
Invoke-WebRequest "$base/$artifact" -OutFile $artifact
Invoke-WebRequest "$base/checksums.txt" -OutFile checksums.txt
Get-FileHash $artifact -Algorithm SHA256
Select-String -Path checksums.txt -SimpleMatch $artifact

Windows · ARM64

$base = 'https://rovito.scubapig.software/downloads/v0.1.0-pilot.2'
$artifact = 'rovito_0.1.0-pilot.2_windows_arm64.zip'
Invoke-WebRequest "$base/$artifact" -OutFile $artifact
Invoke-WebRequest "$base/checksums.txt" -OutFile checksums.txt
Get-FileHash $artifact -Algorithm SHA256
Select-String -Path checksums.txt -SimpleMatch $artifact

Extract the ZIP into a folder you want to keep, then run .\rovito.exe version from that folder in PowerShell. Add the folder to your user PATH to use Rovito from anywhere. Follow your company's policy for unsigned software.

Use the versioned CLI guide after installation. This older build uses rovito auth login --type oauth --name work --policy automation instead of the new login menu. If you have not added Rovito to PATH, use .\rovito.exe in place of rovito.

Update Rovito

On an official Mac installation with the maintenance helper, update from a local terminal:

rovito update

Rovito verifies the signed package and uses sudo for normal administrator approval. Success means the installed CLI and helper have been verified. Your logins and saved connections stay in place. Restart running agent connections to use the new executable.

An older installation first needs the current signed package from Downloads to add the helper. A release without a verified upgrade path, another installation location or a package-manager installation uses the manual route. On Linux, download a newer version into a fresh directory and use its printed executable path. Automatic Linux updates and removal are not provided by these Mac commands.

Ask your agent to update Rovito

For an eligible official Mac installation, first enable requests yourself in a local terminal. This permission is off by default:

rovito update settings --agent-updates on

This covers this user's Rovito agent connections, separately from Bitbucket permissions and release checks. Revoke it with rovito update settings --agent-updates off. The agent checks the release and uses update_apply; you approve the native macOS administrator prompt. No agent shell access or password sharing is needed. A headless client uses your local rovito update command. See the agent update workflow.

After verified installation, reconnect Rovito using your client's connection controls and ask for update_status in the new connection. Confirm the running and installed versions match and restart_required is false. Rovito does not kill or restart connections automatically.

The update and reconnect workflow was tested with Codex CLI on Apple Silicon. Claude has not been verified. Other clients' connection controls may differ.

Check for a release without signing in or installing:

rovito update --check

rovito update --status reads local installed/running versions and maintenance state without network or administrator approval. A failed or old release check does not mean you are up to date. If an older copy still runs, use command -v rovito to see which executable your terminal finds.

A previous update is pending or its outcome is unknown

Inspect rovito update --status before another update. For an unknown outcome, reconcile it in a local terminal:

rovito update --status --reconcile

This inspects the previous operation using normal administrator approval when needed; it does not install again. An unresolved operation blocks another update. A partial installation is not success. Retained verified installers in Downloads provide the manual repair route.

Automatic checks and privacy

Automatic checks are on by default, at most daily during terminal or agent use, never while idle. A terminal check happens after a successful command, waits at most 200 ms and shows at most one notice per release each week. There are no automatic checks during login, help, version commands, CI, scripted output or streamed content.

The request sends no token, account, repository or device ID. The website host can see your IP address and ordinary access logs. Checks never install software or change permissions.

rovito update settings --checks manual

Use --checks auto to restore automatic checks. Set ROVITO_NO_UPDATE_CHECK=1 to disable automatic checks and notices for one process. An explicit rovito update --check still works.

Remove Rovito from a Mac

For a verified official installation, run this as your normal user in a local terminal:

rovito uninstall

Rovito previews the shared installation and this user's selected data, explains that other Mac users lose the command but keep their private data, and asks once. macOS then requests normal administrator approval. Do not run sudo rovito uninstall; Rovito uses its fixed signed maintenance helper. Bitbucket and browser access, projects, downloads, environment credentials and AI-client registrations remain.

To remove only this user's data while keeping the shared program installed:

rovito uninstall --data-only

Rovito shows the selected data and asks once before irreversible removal. This includes saved logins, every entry under the exact rovito Keychain service (including saved Pipeline secrets), settings, named connections and cache. It does not read secret values, sign in or request administrator approval. The shared command, helper and installer receipt remain installed.

To inspect first without changing anything:

rovito uninstall --dry-run

The read-only preview covers standard Rovito configuration/cache folders, saved-profile count, named connections and the shared Mac installation. Add --connection-file /absolute/path/agent.json for an owned, regular file with a supported Rovito connection schema; repeat the flag for each selected custom file and keep the same selection for removal. There is no home-directory scan. --data-only --dry-run is also read-only. Deliberate scripts can confirm with rovito uninstall --yes --output json, but full removal still needs an existing cached sudo approval. --yes cannot bypass safety checks or OS approval.

On Mac, the CLI checks only metadata for service exactly rovito in the configured user Keychain search/default set. It reports presence, absence or unknown per store, never passwords or credential counts. Saved-profile counts come from configuration, not credentials. Unknown, inaccessible or truncated results are not proof of absence or a complete inventory.

Other users' private data, Bitbucket access/content, browser login, projects, external downloads, environment credentials, AI-client registrations, offline/unconfigured stores and unselected custom files remain outside scope. Data-only cleanup keeps the shared program, even when its installation is unverified. Full removal refuses unknown, source and package-manager installations. Removing local credentials does not revoke Bitbucket access.

Finish Rovito commands and close agent connections for every Mac user, including old/custom copies. Active or unresolved updates block removal. Inspect rovito update --status and use rovito update --status --reconcile for an unknown outcome. A changed selection stops before deletion and needs a fresh preview and confirmation.

If removal is partial or its final reply is lost, keep the result and retry rovito uninstall for the recorded user scope, without adding files. If the command is missing, reinstall the verified official package from this guide, then run uninstall again. Normal commands and agent sessions remain blocked while cleanup is unfinished; do not edit or delete .usage.lock or uninstall-progress.json to bypass recovery.

An agent can use uninstall_preview without shell access or prompts. It leaves credential metadata uninspected and offers this CLI dry run for fuller local details.

Shared removal was tested on Apple Silicon. Intel has not been verified.

Troubleshooting

“Command not found” after installing

On Mac, try /usr/local/bin/rovito version. If that works, add /usr/local/bin to your shell's PATH and open a new terminal. On Linux, try ~/.local/bin/rovito version and follow the PATH step above.

macOS blocks the download

Use the signed Mac package from Downloads, not an old archive. If macOS still blocks it, stop and keep the exact error message for support. Do not disable macOS security checks.

Login or a repository read fails

Run rovito auth doctor, or add --profile NAME for a particular login. Check that your keyring is unlocked, the browser used the right Bitbucket account, and that account can access the repository. On Linux, run from your desktop session, not with sudo. Use the recovery instructions it returns. If you need to sign in again, keep the original login method. Never include tokens, callback URLs or passwords in a support request.

The login service is unavailable

New logins and token refreshes need the service. Check your connection and try again. You can use an API token through a separate named login; see authentication alternatives. Rovito does not silently switch credentials or send tokens to another server.

Support

Rovito is maintained by Scubapig Software. Downloads and guides are available here; we do not promise an uptime or support response-time guarantee. Known platform limits are listed above. For a problem, start with troubleshooting and the compatibility notes. Report credential exposure privately using the security policy.

The website uses no analytics or cookies. The login service handles token exchanges in memory and does not store user tokens in its database. The hosting provider may retain connection metadata.

NEXT GUIDEConnect your coding agent