twg-cli headless authentication

[Beau Herger]

This document suggested using TWG over MCP for headless situation like CI.  However, I cannot seem to locate any documentation around environment variables to enable authentication outside of the interactive `twg login`, other than `TWG_BBC_TOKEN` mentioned in Outh 2.1.

[Jovânio Junior]

Hi Beau,

I think the key distinction here is that TWG_BBC_TOKEN is not a general TWG authentication token — it is specifically for Bitbucket, which is currently the exception to TWG CLI’s OAuth model.

For Jira, Confluence and the other Atlassian services, TWG CLI currently documents OAuth 2.1 as the only supported authentication method. The normal flow is:

twg login

which opens a browser, authenticates the user, and stores credentials locally for reuse and automatic refresh.

The current installation documentation also explicitly says that first-time consent and OAuth login require a controlling terminal. Runtime TWG_* credentials can authenticate commands after setup, but they are not used to perform the initial login.

So for CI/headless usage, the model appears to be:

interactive OAuth bootstrap once → persist/provide the resulting credential storage to the CI environment → allow TWG to refresh/reuse those credentials

rather than something like:

TWG_CLIENT_ID + TWG_CLIENT_SECRET

or a service-account-style authentication flow.

There is also an experimental encrypted credential store. On Linux its encryption root key can be supplied through:

TWG_AUTH_STORAGE_KEY

but that only protects/unlocks the stored credentials — it does not replace OAuth authentication itself.

And yes, TWG_BBC_TOKEN can be injected directly in CI, but again that only covers Bitbucket commands. Atlassian explicitly documents it as the CI/CD option for Bitbucket authentication.

So unless Atlassian has an undocumented flow, I don’t think there is currently a true zero-interaction first-time OAuth login for TWG CLI.

That also makes the recommendation to use TWG for CI a little confusing. It works headlessly after authentication has been bootstrapped, but the initial OAuth authorization still appears to require an interactive session.

If the requirement is ephemeral CI runners with no persisted user credentials at all, I think that is currently the important gap.

Hope that helps clarify it.

[Gabriela - LeanZero]

Your reading is right, and the doc closes it rather than leaving it open: "TWG CLI uses OAuth 2.1 as its only supported authentication method. The one exception is Bitbucket, which isn't covered by OAuth yet and requires a separate Bitbucket token." So TWG_BBC_TOKEN being the only environment variable you found is the documented state. You did not miss anything.

One warning before someone offers them to you. TWG_TOKEN and TWG_USER get suggested for this and appear nowhere in the CLI documentation. Neither string appears anywhere on the authentication page.

The absence also looks deliberate. Same page: "Tokens are always entered through secure, interactive terminal prompts that aren't stored in shell history or visible to other processes." An environment variable is exactly the thing that sentence is refusing.

The nearest documented non-browser path is the admin one, which works differently from personal auth. "Site admin and organization admin authentication works differently. It uses an Atlassian Admin API key limited to your organization. This API key is stored in its own config file, so it never interacts with your personal auth.conf." You get there with twg admin auth login --email <your-email> --org <your-org-id>.

That is a key instead of a browser round trip, which is what makes it the closest fit for a runner, with the obvious caveat that it authenticates as an org admin and scopes accordingly. Whether that suits CI depends on what your pipeline actually needs to touch.