Fix common Teamwork Graph CLI issues

If you run into issues with Teamwork Graph CLI, use this page to diagnose common problems, keep the CLI up to date, and get help.

Run all of these troubleshooting commands from your terminal.

Run a health check

To check your authentication, connectivity, and build info, run:

twg doctor

This is always the best first step — it tells you what's working and what isn't.

Repair your setup

If twg doctor reports issues with your configuration or agent skills, run:

twg setup

This re-runs the setup process and refreshes your agent skill files without reinstalling the binary.

If you still encounter errors, check your network connection. If you’re on a VPN, confirm that Atlassian domains are accessible. Once resolved, run twg doctor again to verify.

Update Teamwork Graph CLI

If you're on version 0.9.6 or earlier, twg update may not work correctly. Instead, follow these steps to update it manually.

macOS and Linux — curl installer (recommended for older versions):

curl -fsSL https://teamwork-graph.atlassian.com/cli/install -o twg-install.sh
bash twg-install.sh

Windows — PowerShell:

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

Windows — Command Prompt:

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

If you're on version 0.9.7 or later and want to use the built-in updater:

twg update

To see what's changed in recent versions, view the TWG CLI changelog.

Common issues

Issue	Solution
`Command not found: twg` after installing	Run `ls ~/.local/bin/twg` to confirm TWG CLI was installed. If the file exists, add `~/.local/bin` to your PATH. The installer should have shown you the exact line to add. Restart your terminal, then run `twg --version` to confirm it works.
`~/.local/bin` not in PATH	Add the line printed by the installer to your shell profile (for example, `~/.zshrc` or `~/.bashrc`), then restart your terminal.
Windows SmartScreen warning during install	Select More info, then Run anyway. This is expected for pre-release builds that don't yet have a production code signature.
OAuth authentication expired	Run `twg doctor --basic`, then `twg auth refresh`. If refresh requires sign-in, run `twg login --force` in a normal terminal.
Agent cannot refresh credentials	Give the agent write access to the active TWG config directory, or run `twg auth refresh` outside the sandbox. Consider `twg upkeep enable`.
Agent can see `auth.db` but cannot authenticate	Confirm that it can also access the macOS Keychain or Windows Credential Manager entry. On Linux, provide the same `TWG_AUTH_STORAGE_KEY` to the process.
Linux reports a missing or invalid storage key	Supply the original unpadded base64url-encoded 32-byte key. A different key cannot decrypt the existing database. Do not fall back silently to another key source.
Migration did not complete	Run `twg doctor --basic` to identify the active store. Do not delete `auth.conf` manually. Retry the documented migration only after correcting the reported access problem.
Encrypted database is corrupt or cannot be recovered	Run `twg auth storage reset --yes`, then sign in again with `twg login`. Reset permanently deletes the encrypted credential store and its managed root keys, so any credentials it held are lost and must be set up again.
Bitbucket commands fail	Run `twg setup bitbucket`. Use `--force` only when replacing an existing Bitbucket token. Core `twg login` does not configure Bitbucket.
Agent isn’t using TWG CLI skills	Run `twg skills install` to confirm skills are installed. Check that skills were installed into your project folder (`.agents/skills/twg/`). Some agents only pick up skills from a project-level folder. Restart your agent or editor session after installing.

Share feedback or report a bug

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community