Configure OAuth 2.1

OAuth 2.1 is the default authentication method for Teamwork Graph CLI (TWG CLI). Use these steps to authenticate with your Atlassian account for interactive, day-to-day use. TWG CLI stores credentials under ~/.config/twg/ on macOS and Linux (%APPDATA%\twg on Windows) and reuses them across sessions.

To learn how authentication works, see How authentication works.

Configure OAuth 2.1

1. In your terminal, run:

   1
   2
   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.
   • 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:

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

Verify your authentication

To confirm authentication is working, run:

1
2
twg doctor

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

Re-authenticate

To update your credentials at any time:

1
2
twg login

To force a full re-entry of all credentials:

1
2
twg login --force

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:

1
2
twg auth refresh

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

1
2
twg auth refresh --force

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:

1
2
twg upkeep enable

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:

1
2
twg upkeep status
twg upkeep run
twg upkeep disable

TWG CLI uses a macOS LaunchAgent, Linux systemd 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 systemd 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:

1
2
twg setup bitbucket

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

Next steps

• How authentication works
• Troubleshoot TWG CLI