Install & Setup TWG CLI

1. CLI installation mode

Use this mode when you want to install and authenticate TWG CLI directly from your terminal.

Before you begin

You need macOS (arm64 or x64), Linux (arm64 or x64), or Windows (arm64 or x64).
You need an Atlassian account with access to the products you want to use.
To use TWG CLI through an agent after CLI setup, you need an AI coding agent installed on your computer.

The TWG CLI binary does not require a separate runtime (for example, no Node.js).

Leave TWG_AGENT_DEFAULTS unset during interactive installation and setup so consent and login prompts work. If it's already set, see troubleshooting.

Step 1: Install TWG CLI

macOS and Linux

Recommended:

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

During setup:

First-time consent and OAuth login require a controlling terminal.
Setup installs and refreshes TWG agent skills.
The installer opens your browser to sign in with OAuth. Sign in to Atlassian, select the site you want to authorize (auto-selected if you have access to only one), review the requested permissions, and select Accept.
After core setup and twg doctor pass, setup may offer to configure the optional Bitbucket token. If you skip it, TWG CLI is still ready for non-Bitbucket commands.

The installer completes setup and runs twg doctor automatically. To repair setup later:

twg setup

Run installation from a terminal when consent or login is needed. Runtime TWG_* credentials authenticate commands and twg doctor, but are not used by login.

On macOS, setup may enable a background helper and show a system notification for Atlassian Pty Ltd or twg. This is expected; see Configure OAuth 2.1 for details.

To install a specific version:

curl -fsSL --retry 2 https://teamwork-graph.atlassian.com/cli/install | bash -s -- --version 0.9.1

If ~/.local/bin is not in your PATH, the installer prints the exact line to add to your shell profile.

Install with the macOS package

Install TWG for your user account using either method below. The package installs twg to ~/.local/bin/twg and adds ~/.local/bin to your PATH. No sudo or administrator password is required.

Manual installation

Download install.pkg.
Open the downloaded package in Finder and follow the installer prompts.
Open a new terminal to load the PATH change.

When you are ready to authenticate and configure TWG, run:

twg setup
twg doctor

Silent installation

Run this command to install TWG without an interactive terminal, sign-in prompts, or setup prompts:

pkg=$(mktemp -d) && curl -fsSL https://teamwork-graph.atlassian.com/cli/install.pkg -o "$pkg/install.pkg" && /usr/sbin/installer -pkg "$pkg/install.pkg" -target CurrentUserHomeDirectory >/dev/null

For current-user package installations, twg upgrade (or twg update) silently installs the latest stable macOS package without sudo. It verifies the immutable package checksum, Atlassian signing identity, and package identifier/version before installation. Use --check to check without installing. Package upgrades do not support beta or pinning a version other than the latest published package.

Legacy system-wide installations at /usr/local/bin/twg receive migration instructions instead. Install the current-user package, put ~/.local/bin before /usr/local/bin in PATH, and open a new terminal or invoke ~/.local/bin/twg explicitly. The user package does not replace the legacy binary.

The downloaded package remains in the temporary directory shown by echo "$pkg". Open a new terminal to use twg, or run export PATH="$HOME/.local/bin:$PATH" in the current shell.

To upgrade, download and install the latest package using either method.

Windows

Use Windows PowerShell or Command Prompt for Windows installation. Don't run the Windows installer from Git Bash, MINGW, WSL, or another bash-like shell.

Install — PowerShell

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

Install — Command Prompt (cmd)

curl.exe -fsSL https://teamwork-graph.atlassian.com/cli/install.ps1 -o twg-install.ps1
powershell -ExecutionPolicy Bypass -File twg-install.ps1

The Windows installer performs the same interactive setup as macOS and Linux: binary install, checksum verification, consent, skill install, OAuth login, and doctor verification.

Install with a Windows MSI

Use the signed MSI for a current-user installation without administrator approval. Choose the package that matches your device:

Windows x64 MSI for most Windows PCs
Windows ARM64 MSI for Windows on ARM

Download the MSI and double-click it, or install silently from a normal PowerShell session as the intended user. The following commands install without installer UI, password prompts, or a restart:

Invoke-WebRequest https://teamwork-graph.atlassian.com/cli/twg-windows-x64.msi -OutFile twg-windows-x64.msi
msiexec.exe /i "$PWD\twg-windows-x64.msi" /qn /norestart

For Windows on ARM, replace x64 with arm64 in both commands. The MSI installs twg.exe to %LOCALAPPDATA%\Programs\twg-msi and adds that directory to the user PATH for newly opened terminals.

The MSI installs only the CLI binary and does not launch login or setup. When you are ready to configure skills and authentication, open a new PowerShell or Command Prompt window and run:

twg setup
twg doctor

For current-user MSI installations, twg upgrade (or twg update) downloads and silently installs the latest published stable MSI for your architecture. It verifies the package checksum and identity before installation. Use --check to check without installing. MSI upgrades do not support beta, downgrades, or pinning a version other than the published MSI. Legacy machine-wide installations still require the migration below.

Per-user MSIs replace earlier per-user MSIs of the same architecture. The per-user MSI refuses a fresh installation while an older machine-wide C:\Program Files\twg\twg.exe remains. Remove the old package before installing the per-user MSI, using the state-preserving migration below. Do not uninstall the old MSI through Settings after installing the new one: its bundled cleanup code can delete authentication and setup shared by the new installation. Direct PowerShell installations remain separate; use Get-Command -All twg to inspect PATH resolution.

For migration, obtain the exact MSI used for the machine-wide installation and run the helper from the TWG CLI source checkout (twg-cli/) in an elevated PowerShell session:

powershell -NoProfile -File bin/release/migrate-windows-machine-msi.ps1 -MsiPath "C:\path\to\legacy-twg.msi"

The helper checks that the installed package supports suppressing user-data cleanup, then removes it silently with that protection enabled. It refuses unsupported packages before uninstalling anything. After it succeeds, return to a normal PowerShell session and install the new MSI with /qn /norestart. This one-time removal of a machine-wide package requires administrator approval; fresh per-user installs do not.

You can also install the latest MSI manually or use your organization's device-management process.

Run the Windows installer from a console when consent or login is needed. Runtime TWG_* credentials authenticate commands and twg doctor, but are not used by login.

During setup, the installer:

Opens your browser to sign in with OAuth. In the browser, select the site you want to authorize (auto-selected if you have access to only one), review the requested permissions, and select Accept.
Offers the optional Bitbucket token step. You can skip this unless you plan to use Bitbucket-specific commands.

Credentials are saved in the TWG config directory and reused across sessions. For re-authentication and the Bitbucket token, see Configure OAuth 2.1.

After installation, open a new PowerShell or Command Prompt window and run:

twg doctor

If Windows doesn't recognize twg, close and reopen the terminal so PATH changes are loaded, then try again.

2. Agent installation mode

Use this mode when you want an AI coding agent to install TWG CLI, authenticate, and set up agent skills for you.

Copy the following prompt and paste it into your agent:

Install/setup TWG using https://teamwork-graph.atlassian.com/cli/AGENTS.md

The agent should use that hosted AGENTS.md directly. There are no separate agent-specific install URLs.

Verify setup

Run:

twg doctor

This checks authentication, connectivity, and build info. It works the same on macOS, Linux, PowerShell, and cmd.

Try it

Your AI coding agent can now access your Atlassian data across Jira, Confluence, Bitbucket, and more. Describe what you want in plain language and your agent handles the rest:

"Summarize the work I did this week"
"What are my open Jira issues?"
"Create a Confluence page about our Q2 goals"
"Show the current sprint for my team"

See Agent examples for more prompts to try.

To discover command syntax directly in the terminal, run:

twg --help
twg confluence --help
twg jira --help

Upgrade

Run the built-in upgrader:

twg upgrade

TWG CLI checks for upgrades during normal use and notifies you when a new version is available.

Scheduled upkeep also sends desktop upgrade notifications titled Atlassian Teamwork Graph CLI (twg). The message names the scheduled upkeep job as the source and includes twg upgrade and twg upkeep disable. To stop scheduled OAuth maintenance and desktop notifications, run twg upkeep disable.

Uninstall

Preview the files and configs that would be removed:

twg uninstall --dry-run

Uninstall asks for confirmation, revokes stored credentials, and removes the binary, installer-owned skill bundles, PATH changes, caches, consent, and all local TWG configs:

twg uninstall

Beta upgrades

To receive pre-release upgrades before they reach the stable channel, use the beta channel.

First install via beta

bash <(curl -fsSL https://teamwork-graph.atlassian.com/cli/beta/install)

Installs from the beta channel record the channel preference automatically — future twg upgrade calls continue to check the beta channel.

Switch an existing install to beta

twg upgrade --channel beta

Switch back to stable

twg upgrade --channel stable

Beta releases are usually ahead of stable, so returning to stable normally means moving your binary to an older version. In that case, the command records the stable preference, reports the version difference, and leaves the binary alone. To install the stable release over the newer beta build, confirm the downgrade:

twg upgrade --channel stable --yes

Until you confirm, twg upgrade and twg upgrade --check report that your installed build is ahead of the channel you follow, along with the command that resolves it, instead of reporting that the CLI is up to date.

Feedback

To share feedback or report an issue, use the CLI:

twg feedback --summary "<short title>"

The command opens a prefilled public form in interactive terminals. In agent, structured-output, or non-interactive runs, it prints the form URL instead. Your configured TWG account email is prefilled when available. Review the details, provide an email if needed, complete reCAPTCHA, and submit the form. TWG authentication is not required.

You can also open the TWG CLI feedback form directly.