Configure OAuth 2.1

Teamwork Graph CLI (TWG CLI) uses OAuth 2.1 for personal sign-in. Bitbucket commands use a separate token. TWG CLI stores credentials under ~/.config/twg/ on macOS and Linux, or %APPDATA%\twg on Windows.

To learn how authentication works, see How authentication works.

Sign in with OAuth 2.1

1. In your terminal, run:

   1
   2
   twg login
   

   TWG CLI displays a verification URL and short code and offers to open your browser. If it doesn't open, copy the URL and open it manually.

2. In your browser:

   • Select the site to authorize, if prompted.
   • Review the requested permissions and select Accept.

3. Return to your terminal and choose the profile's default site if prompted. A single accessible site is selected automatically; twg login --site <site> skips the picker. TWG CLI verifies the site's organization and confirms when your credentials are saved.

Manage login profiles

Login profiles are available in TWG CLI v1.3.6 and later. Use them to keep separate logins for different organizations. Each profile stores its own login, organization, default site, and optional Bitbucket token.

Create and list profiles

To sign in to another organization, create a named profile:

1
2
3
twg login --new-profile work
twg auth profile list

TWG allows one profile per organization. To replace an existing login, see Update or remove a profile.

You can also let TWG choose a name:

1
2
twg login --new-profile

Profile names follow these rules:

• Generated names combine the site and authentication method, such as hello-oauth. For .atlassian.net sites, TWG uses the site prefix. For other hostnames, it keeps the full hostname and replaces dots with hyphens.
• Name collisions add -2, -3, and so on to generated names. If you supply a name that already exists, TWG rejects it before sign-in starts.
• The name default is reserved, regardless of capitalization. You can't create or rename a profile to use it.

Choose a profile for a command

Use the saved default profile and its default site:

1
2
twg jira workitem get ABC-1

Choose a site and let TWG select the profile for that site's organization:

1
2
twg jira workitem get ABC-1 --site personal-site

Choose both the site and the login:

1
2
twg jira workitem get ABC-1 --site personal-site --profile personal

• --profile personal keeps the command on that login. If the organization doesn't match or the account can't access the item, TWG returns an error without trying another login.
• --profile default selects the saved default profile, whatever its name.
• Set TWG_PROFILE=work in your shell to select work across commands. A command-line --profile personal overrides it. Both selectors keep the chosen login even when you supply --site.

For the full selection order, see Login profiles.

Change your defaults

• Default profile: Run twg auth profile default work.
• Default site and matching profile: Run twg setup default-site --site <site>.

Signing in again preserves the default. Choosing a profile for one command does not change the saved default.

Update or remove a profile

To replace a profile's saved login credentials, run:

1
2
twg login --profile work --force

To remove a profile and its credentials, run:

1
2
twg logout --profile work

Upgrade from a single login

Your existing login keeps working after you upgrade:

• When you run a command that writes profile data, TWG imports your saved credentials without requiring browser sign-in.
• If the imported login lacks organization details, TWG verifies them when needed.
• Signing in again with --profile verifies that profile independently of other imported logins.
• Automatic profile selection and new-profile creation need organization details to choose the right login or detect an existing profile for the same organization.

Enable experimental encrypted credential storage

TWG CLI can store encrypted credentials in auth-storage/auth.db. This experimental option keeps the root key separate: in the OS vault by default on macOS and Windows, or supplied through TWG_AUTH_STORAGE_KEY on any supported OS. This protects credentials from software that can read local files but cannot access the root key.

macOS

Encrypted storage uses macOS Keychain for the root key by default.

If you already use TWG CLI, migrate your existing credentials:

1
2
twg auth storage migrate

The command asks before switching between file storage (auth-profiles.json) and encrypted storage (auth.db). It preserves credentials and defaults, including single-login auth.conf installations. Use --yes for an already-confirmed script.

If you are signing in for the first time, save the login directly to encrypted storage:

1
2
TWG_SECRET_STORE=keychain twg login --force --oauth

TWG_SECRET_STORE only applies to login; it does not need to remain set.

Windows

Encrypted storage uses Windows Credential Manager for the root key by default.

In PowerShell, migrate existing credentials:

1
2
twg auth storage migrate

If you are signing in for the first time:

1
2
$env:TWG_SECRET_STORE = "keychain"; twg login --force --oauth

In Command Prompt, migrate existing credentials:

1
2
twg auth storage migrate

If you are signing in for the first time:

1
2
set TWG_SECRET_STORE=keychain && twg login --force --oauth

The setting applies only to the current shell session; you do not need to persist it.

Linux

Linux requires TWG_AUTH_STORAGE_KEY for each command. To migrate existing credentials:

1
2
TWG_AUTH_STORAGE_KEY=<your-key> twg auth storage migrate

If you are signing in for the first time:

1
2
TWG_SECRET_STORE=keychain TWG_AUTH_STORAGE_KEY=<your-key> twg login --force --oauth

Use an unpadded base64url encoding of a random 32-byte root key. Supply the same TWG_AUTH_STORAGE_KEY for every command that uses this database, on any supported OS. A new key cannot convert or unlock an OS-vault database. For example:

1
2
TWG_AUTH_STORAGE_KEY=8XecAMpUKloUsQfQnmk_y0PEgOB4p4lIsvFjL1d0TT8

Generate and protect your own key; do not reuse this example.

Verify encrypted storage

To confirm which storage method is in use, run:

1
2
twg doctor --basic

On macOS with encrypted storage enabled, the output includes:

1
2
3
4
5
6
Connectivity
  Status: ok
  Token: valid
  Auth source: ~/.config/twg/auth-storage/auth.db (encrypted; root key in OS vault)
  Message: Authenticated successfully. OAuth token is valid for the configured endpoint.

The Auth source identifies the credential store and whether its root key comes from the OS vault or environment.

Coding-agent access

A coding agent using encrypted storage needs:

• Permission to read the relevant macOS Keychain or Windows Credential Manager item, or access to the database's TWG_AUTH_STORAGE_KEY for environment-key storage.
• Read access to the active TWG config directory and auth.db.
• Write access to the config directory when refreshing credentials, logging in, or recovering an interrupted database update. The CLI may need to create temporary files while saving changes.

Give the agent only the access it needs. Keep the root key and OAuth token out of prompts, chat, and command arguments; supply the key through the environment.

To refresh credentials outside the agent sandbox, enable OAuth upkeep:

1
2
twg upkeep enable

twg setup enables upkeep automatically. The helper runs as your user and refreshes credentials in the background. It does not retain TWG_AUTH_STORAGE_KEY; refresh an environment-key database in a normal terminal with the same key. If an agent cannot access the config directory or OS vault, use twg doctor --basic or twg auth refresh in a normal terminal, or update its sandbox permissions.

For a fuller authentication and connectivity check, run:

1
2
twg doctor

Add --site <site> or --profile <name> to check a particular login. Doctor reports the selected profile, storage path, and authentication method.

Re-authenticate

To sign in again:

1
2
twg login

To restart sign-in and replace saved credentials:

1
2
twg login --force

Refresh OAuth credentials

TWG CLI normally refreshes OAuth credentials before they expire. To check every profile without signing in:

1
2
twg auth refresh

If the credentials are still fresh, the command makes no changes. Use --force only for manual repair or validation:

1
2
twg auth refresh --force

Add --profile work or --profile default to refresh only that profile. Without the flag, refresh checks all profiles, even if TWG_PROFILE is set. A failed refresh does not stop the others.

Before refreshing, TWG CLI checks that it can save the updated credentials. If the config directory isn't writable, it 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.

OAuth upkeep background helper

Upkeep is a per-user background helper that runs outside coding-agent sandboxes. It keeps OAuth credentials fresh and checks for CLI upgrades. twg setup enables it during installation. To enable or repair it later:

1
2
twg upkeep enable

Every 12 minutes, upkeep checks OAuth credentials for all profiles. It checks for CLI upgrades at most once a day and sends limited reminders to run twg upgrade when one is available. It never downloads or installs upgrades automatically.

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

1
2
3
4
twg upkeep status
twg upkeep run
twg upkeep disable

TWG CLI uses a macOS LaunchAgent, Linux systemd user timer, or Windows Scheduled Task to run the helper as your user.

On Linux, scheduling requires a systemd user instance and an active user D-Bus session. If setup cannot install the schedule, retry twg upkeep enable after fixing the reported system error.

Upkeep stores non-secret maintenance state in upkeep.json. It stays enabled after twg logout and checks any remaining profiles. twg uninstall disables it, attempts to revoke stored OAuth credentials, and removes the CLI and local TWG configs.

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

Bitbucket authentication

Bitbucket commands require a separate token attached to your Atlassian login profile. Sign in first, then set it up with:

1
2
twg setup bitbucket

twg setup also offers this during setup. A valid existing token is reused. If the token is invalid or expired, twg setup bitbucket starts token setup again automatically. Pass --force to replace a token without checking it first:

1
2
twg setup bitbucket --force

Add --profile work to attach the token to a particular login.

For CI/CD, set the TWG_BBC_TOKEN environment variable to your Bitbucket token. If it is set when you replace a token through setup, update or unset it afterward because it overrides the saved token.

Next steps

• How authentication works
• Troubleshoot TWG CLI