Fix common TWG CLI issues

If your Teamwork Graph (TWG) CLI setup isn't working as expected, use this guide to diagnose and fix common issues. Each section covers a specific problem with steps to resolve it, so you can get back to working with your Atlassian tools quickly.

Common issues

"Command not found: twg" after installing

Your shell can't find the TWG CLI binary. This usually means the install directory isn't in your PATH.

To fix:

1. Run ls ~/.local/bin/twg to confirm TWG CLI was installed.

2. If the file exists, add ~/.local/bin to your PATH. The installer should have shown you the exact line to add.

3. Restart your terminal, then run twg --version to confirm it works.

Authentication fails or "Unauthorized" error

You might see this error for several reasons:

Wrong API token type: You must use a classic (unscoped) API token, not a scoped token. See Get started with TWG CLI.

Token expired or revoked: Create a new token at id.atlassian.com and run twg login again.

Wrong site name: The site name should be just the subdomain, for example mycompany not mycompany.atlassian.net.

Wrong email: Confirm that the email matches your Atlassian account.

Your agent isn't using TWG CLI skills

Your agent isn't querying Atlassian data even though TWG CLI is installed.

To fix:

1. Run twg skills install to confirm skills are installed.

2. Check that skills were installed into your project folder (.agents/skills/twg/). Some agents only pick up skills from a project-level folder.

3. Restart your agent or editor session after installing.

Windows SmartScreen warning during install

Windows may show a SmartScreen warning when you run the installer.

To proceed: Select More info, then select Run anyway.

Bitbucket commands return errors

If Bitbucket-specific prompts fail but Jira and Confluence work, you might not have configured a Bitbucket app password.

To fix: Run twg login again and follow the prompts to enter your Bitbucket app password. Once complete, retry your Bitbucket command to verify it works.

Check your setup with twg doctor

TWG CLI includes a built-in diagnostic command that checks whether your setup is working correctly.

Run the check

Each check shows as pass or fail with a short message.

What twg doctor checks

If a check fails

Build info: Re-install TWG CLI. See Get started with TWG CLI. Once complete, run twg doctor again to verify.

Authentication: Run twg login again. See Get started with TWG CLI. Once complete, run twg doctor again to verify.

API connectivity: Check your network connection and confirm your API token is valid. If you're on a VPN, confirm that Atlassian domains are accessible. Once resolved, run twg doctor again to verify.

Skills installed: Run twg skills install. See Get started with TWG CLI. Once complete, run twg doctor again to verify.