Configure OAuth 2.1

OAuth 2.1 is the only supported sign-in method for Atlassian data in Teamwork Graph CLI (TWG CLI). 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, then opens 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. TWG CLI confirms when your credentials are saved.

Enable experimental encrypted credential storage

TWG CLI now has an experimental option to store encrypted credentials in its vault at auth-storage/auth.db. Its root key is stored separately: in the OS vault on macOS and Windows, or in the TWG_AUTH_STORAGE_KEY environment variable on Linux. This helps protect credentials from software that can inspect local files but cannot access the root key.

macOS

Encrypted storage uses macOS Keychain for the root key.

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

1
2
twg auth storage migrate

This detects your active storage and asks before migrating to the other backend. With auth.conf active, it copies your credentials to encrypted storage, then deletes auth.conf so TWG CLI uses auth.db. With encrypted storage active, it copies the selected profile back to auth.conf, then resets encrypted storage and its other profile slots. 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.

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 does not use an OS vault for this option. Provide the root key with 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

The TWG_AUTH_STORAGE_KEY value must be an unpadded base64url encoding of a random 32-byte root key. It is used instead of an OS vault for that command. For example:

1
2
TWG_AUTH_STORAGE_KEY=8XecAMpUKloUsQfQnmk_y0PEgOB4p4lIsvFjL1d0TT8

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

Verify encrypted storage

After either path, use twg doctor --basic to confirm which storage method is in use:

1
2
twg doctor --basic

On macOS with encrypted storage enabled, the output includes an entry like this:

1
2
3
4
5
6
7
8
9
10
11
12
Build
  Version: 1.2.8
  Commit: abcdef
  Profile: external
  Built at: 1 minute ago

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.db file contains encrypted credentials. The root key is held separately by Keychain or Windows Credential Manager. On Linux, it is supplied through TWG_AUTH_STORAGE_KEY instead.

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 TWG_AUTH_STORAGE_KEY on Linux.
• 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. On Linux, make TWG_AUTH_STORAGE_KEY available only to the commands that need it.

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 OAuth credentials in the background. On Linux, it does not retain TWG_AUTH_STORAGE_KEY; refresh encrypted storage in a normal terminal with the same key. If the agent still cannot access the config directory or OS vault, run twg doctor --basic or twg auth refresh in a normal terminal, or update the agent's sandbox permissions.

For a fuller authentication and connectivity check, run:

1
2
twg doctor

This checks your credentials, token status, and connected site.

Re-authenticate

To sign in again:

1
2
twg login

To restart the OAuth sign-in flow and replace saved credentials:

1
2
twg login --force

Refresh OAuth credentials

TWG CLI normally refreshes OAuth credentials before they expire. To check for a refresh 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

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

The helper runs every 12 minutes. It refreshes OAuth when needed and checks for CLI upgrades at most once a day. When an upgrade is available, it sends an initial notification, followed by limited reminders. Each notification tells you to run twg upgrade; upkeep 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.

The helper stores only non-secret maintenance state in upkeep.json under the TWG config directory. twg logout leaves it enabled but skips auth work until you sign in again. twg uninstall disables it, revokes stored 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. twg login does not prompt for it. Set it up with:

1
2
twg setup bitbucket

twg setup also offers this during setup. An existing token is reused; pass --force to replace it:

1
2
twg setup bitbucket --force

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

Next steps

• How authentication works
• Troubleshoot TWG CLI