Troubleshoot TWG CLI
Use this page to diagnose problems with Teamwork Graph CLI (TWG CLI), upgrade it, and get help.
Run a health check
To check your authentication, connectivity, and build info, run:
twg doctor
Doctor shows which login and credential store it uses. To check another login or site, add --profile <name> or --site <site>. --profile default checks the saved default, whatever its name.
Run twg auth profile list to see available profiles. If no default is saved, choose one with twg auth profile default <name>.
If --profile fails with AUTH_MIGRATION_REQUIRED, the login was saved before 1.3.6. Run twg auth profile migrate once, then retry. Commands without --profile keep using that login without migrating.
If site selection fails or is ambiguous, select the intended profile and check its access:
twg access --site <site> --profile <name>
An explicit profile stays selected after a site or permission error. TWG doesn't try another login.
An imported single-login configuration may lack organization details. TWG verifies them when needed; an unavailable or incomplete lookup leaves saved mappings and defaults unchanged, though OAuth tokens may refresh. For a selected profile, sign in again with:
twg login --profile <name> --force
This verifies the selected profile without depending on unrelated imports. Automatic selection and new-profile creation still require enough organization information to choose a login or reject a duplicate. If those lookups fail, retry them or select the profile explicitly.
A profile marked deletion pending has a saved site or organization mapping that no longer matches the current mapping. If the saved details are correct, try signing in again with --profile <name> --force. Otherwise, remove it with twg logout --profile <name> and sign in again.
Repair your setup
If twg doctor reports issues with your configuration or agent skills, run:
twg setup
This refreshes your setup and agent skill files without reinstalling the binary.
Interactive consent or sign-in is unavailable
If setup reports that interactive auth prompting is unavailable, use an interactive terminal with text output.
If you previously exported TWG_AGENT_DEFAULTS=1 in that terminal, remove it before retrying:
| Shell | Command |
|---|---|
| macOS or Linux (bash or zsh) | unset TWG_AGENT_DEFAULTS |
| Windows PowerShell | Remove-Item Env:TWG_AGENT_DEFAULTS -ErrorAction SilentlyContinue |
| Windows Command Prompt | set TWG_AGENT_DEFAULTS= |
Remove the setting from your shell startup file too, if you added it there. Then rerun the installer or twg setup.
Upgrade TWG CLI
If you're on version 0.9.6 or earlier, twg upgrade may not work correctly. Use the manual upgrade steps below instead.
macOS and Linux (curl installer, recommended for older versions)
curl -fsSL --retry 2 https://teamwork-graph.atlassian.com/cli/install | bash
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 upgrader, run:
twg upgrade
For full installation options, see Set up TWG CLI.
Get help and give feedback
To see what's changed in recent versions, view the changelog.
To give feedback or report an issue, use the CLI to submit feedback with prefilled details, or submit feedback directly through the TWG CLI feedback form.
Review the details, provide an email if needed, complete reCAPTCHA, and submit the form.