Configure OAuth 2.1 for Teamwork Graph CLI

OAuth 2.1 is the default authentication method for using the Teamwork Graph CLI. Use these steps to authenticate with your Atlassian account for interactive, day-to-day use.

More about how Teamwork Graph CLI auth works

Configure OAuth 2.1

1. In your terminal, run:

   twg login

   TWG CLI displays a verification URL and a short user code, then opens your browser automatically. If the browser doesn't open, copy the URL and open it manually.

2. In your browser:

   • Select your Atlassian organization if you have more than one. If you have access to only one site, it's selected automatically.

   • Select the site you want to authorize (for example, mycompany.atlassian.net). If you have access to only one site, it's selected automatically.

   • Review the permissions the CLI is requesting, then select Accept.

3. Return to your terminal. When authentication is complete, you see a confirmation:

   ✔ Authentication successful! ✔ Authenticated as [your name] ✔ Credentials saved to ~/.config/twg/auth.conf

Verify your authentication

To confirm authentication is working, run:

This checks your credentials and confirms your auth method, token status, and connected site.

Re-authenticate

To update your credentials at any time:

To force a full re-entry of all credentials:

Refresh OAuth credentials

TWG CLI normally refreshes OAuth credentials after 75% of the access-token lifetime has elapsed. To run that same non-interactive check explicitly:

The command returns successfully without rotating when the credentials are still fresh. Use --force only for manual repair or validation:

Before contacting the OAuth token endpoint, TWG CLI verifies that it can atomically update the active credential backend. This prevents a sandboxed coding agent from spending a one-time refresh token and then losing the rotated replacement.

If the config directory isn't writable, TWG CLI sends no refresh request and asks you to run twg auth refresh in a normal terminal. It also detects common coding agents and prints the relevant configuration.

Keep OAuth working inside coding agents

Coding agents often run commands in sandboxes that can't reliably update credentials outside the workspace. TWG CLI handles this by installing a small per-user upkeep helper during setup. The helper runs outside the agent sandbox, keeps OAuth credentials fresh, and sends update notifications when a new CLI version is available.

Keep upkeep enabled so agents can continue using TWG CLI without spending a one-time refresh token from inside a sandbox.

OAuth upkeep background helper

twg setup enables upkeep automatically. To repair or re-enable it manually:

The scheduler runs every 12 minutes. It refreshes OAuth only when the normal refresh threshold is within 15 minutes and checks for CLI updates at most daily with jitter.

When an update is available, it sends an initial native notification, up to three daily reminders, then up to three weekly reminders until you update. Each notification tells you to run twg update; upkeep never downloads or installs updates automatically.

Use these commands to inspect, run, or remove it:

TWG CLI uses a macOS LaunchAgent, Linux system user timer, or Windows Scheduled Task. The schedule invokes the stable TWG launcher so normal updates can replace the runtime safely. OAuth refresh still uses the same persistence preflight, cross-process lock, and atomic credential save as foreground commands.

On Linux, scheduling requires a system user instance and an active user D-Bus session. If setup can't install the schedule, it completes with repair guidance. Retrying twg upkeep enable reports the underlying systemctl --user error and leaves upkeep disabled.

The scheduler stores only non-secret maintenance state in upkeep.json under the active TWG config directory. twg logout leaves the schedule enabled but silently skips auth work until OAuth is configured again. twg uninstall disables the schedule, revokes stored credentials, and removes the CLI and all local TWG configs.

If you disable the background item, TWG CLI still works, but OAuth refresh and update notifications may not run in the background. Run twg auth refresh or twg update manually if needed.

If a command says the TWG config directory isn't writable, run twg auth refresh or twg login in a normal terminal outside the coding agent.

Bitbucket authentication

Bitbucket is the only exception to OAuth support: Bitbucket commands aren't covered by OAuth yet and require a separate Bitbucket token. When you run twg login, you're prompted for your Bitbucket token. twg login preserves an existing Bitbucket token unless you run twg login --force.

To set or refresh the Bitbucket token later without rerunning core authentication, run:

For CI/CD, set the TWG_BBC_TOKEN environment variable to your Bitbucket token.

Share feedback or report a bug