Authentication

TWG CLI uses OAuth by default, stores credentials under ~/.config/twg/ on macOS and Linux (%APPDATA%\twg on Windows), and reuses them across sessions. Use this page to refresh OAuth credentials, re-authenticate, or configure API tokens for CI/CD.

Re-authenticate

To update your credentials at any time:

twg login

To force a full re-entry of all credentials:

twg login --force

Refresh OAuth credentials

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

twg auth refresh

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

twg auth refresh --force

Before contacting the OAuth token endpoint, TWG 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 is not writable, TWG 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. For the default macOS/Linux config root, the equivalent settings are:

Codex

Add or merge this in ~/.codex/config.toml:

default_permissions = "twg-workspace"

[permissions.twg-workspace]
extends = ":workspace"

[permissions.twg-workspace.filesystem]
"~/.config/twg" = "write"

Codex permission profiles replace the legacy sandbox_mode and sandbox_workspace_write settings. Do not configure both forms together.

Claude Code

Add or merge this in ~/.claude/settings.json:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.config/twg"]
    }
  }
}

Cursor

Add or merge this in ~/.cursor/sandbox.json:

{
  "type": "workspace_readwrite",
  "additionalReadwritePaths": ["/Users/your-user/.config/twg"]
}

Gemini CLI (macOS and Linux)

For container sandboxing, add the config directory as a read-write mount:

SANDBOX_MOUNTS=/Users/your-user/.config/twg:/Users/your-user/.config/twg:rw

For Windows, custom TWG_CONFIG_DIR, XDG, WSL, and other layouts, use the exact path printed by TWG. Gemini CLI does not document a portable Windows SANDBOX_MOUNTS form for this path, so run twg auth refresh outside the agent unless you have explicitly configured an equivalent sandbox mount. For agents without a verified persistent directory rule, use the terminal fallback.

Scheduled OAuth upkeep

twg setup enables the per-user scheduler automatically to maintain OAuth outside coding-agent sandboxes. To repair or re-enable it manually:

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:

twg upkeep status
twg upkeep run
twg upkeep disable

TWG 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 cannot 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 and removes its state before deleting the CLI.

Create a TWG API token

API tokens remain available for scripted environments and compatibility flows. A single API token supports TWG commands across Jira, Confluence, Rovo Search, and more. The token page is selected by the binary's configured token mode: classic-token binaries open the standard Atlassian API-token page, while scoped-token binaries open the TWG-scoped token page.

Bitbucket-specific commands require a separate Bitbucket token. To configure or refresh it without rerunning core TWG authentication, run:

twg setup bitbucket

twg login preserves an existing Bitbucket token unless you run twg login --force.

twg login opens your browser automatically to the token creation page. If you need to create a TWG-scoped token manually:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.
2. Click Create API token with scopes and accept the pre-filled settings.
3. Copy the token value and paste it when twg login prompts you.

Use environment variables

For CI/CD and scripted use, set the following variables instead of running twg login:

Next steps

• Agent skills
• Agent examples