capa auth

Authenticate with Git hosts manually so CAPA can access private repositories via OAuth tokens stored in your local CAPA database. The command ensures the CAPA server is running, then either lists current connections or starts the OAuth flow in your browser.

Usage

capa auth [provider]

If you omit provider, CAPA prints every connected Git host and usage hints instead of opening a login flow.

Description

When you run capa auth, CAPA loads your settings and local database path, starts the CAPA server (matching your installed CLI version), and fails fast if the server cannot be reached. Successful runs always show the effective server URL; OAuth and integration links refer to that same base URL.

List mode (capa auth with no arguments)

CAPA enumerates OAuth tokens recorded for Git providers:

  • No connections: you see an empty-state message followed by usage and examples.
  • For each connected host: the provider hostname (shown with GitHub or GitLab in the CLI output). If the token carries an expiry time, the CLI reports expiration in local time, whether it has already expired, or whether it expires within about an hour. If a refresh token is present, the CLI notes that auto-refresh is enabled; otherwise it warns that you will need manual re-auth after expiration. Tokens without expiry are labeled as having no expiration.
  • The command then prints reminder lines for authenticating (capa auth <provider>) and directs you to the web UI integrations page for GitHub Enterprise, GitLab Self-Managed, and other self-hosted instances (see below).

Authenticate (capa auth <provider>)

Provider hostname

provider must look like a domain name (ASCII letters, numbers, hyphen or dot-separated labels, ending in a suffix such as .com). Invalid domains result in an error and exit.

Hosted GitHub.com and GitLab.com only via CLI

The OAuth flow wired to this command only supports:

  • github.com — mapped internally to GitHub OAuth
  • gitlab.com — mapped internally to GitLab OAuth

Any other valid hostname — including GitHub Enterprise Server or self-managed GitLab — is rejected by the CLI with instructions to complete setup in the web UI under /ui/integrations on your running CAPA server (the full URL is printed and matches the server URL shown at startup).

Existing token behavior

If a non-expired token already exists for the requested host, CAPA skips OAuth, prints confirmation with expiry summary (approximate hours until expiry when applicable, and whether a refresh token is stored), and tells you how to revoke or disconnect first if you need to sign in again. Tokens with no expires_at value are treated as non-expiring. If the stored token has an expiry time that is already past, the CLI announces that it will re-authenticate and continues into the OAuth flow.

OAuth flow steps

  1. CAPA calls POST /api/integrations/github/oauth/start or POST /api/integrations/gitlab/oauth/start on the local server to obtain an authorization URL and flow id.
  2. It tries to open that URL in your default browser (open on macOS, start on Windows, xdg-open on Linux). If opening fails, the URL is printed for manual copy-and-paste.
  3. The CLI waits for authorization by polling your local database for a stored token (poll interval two seconds; five-minute ceiling). Finish the consent screen in the browser within that window; on success CAPA confirms and prints expiry and refresh-token details when applicable. Timeout or abandonment yields a failure exit.

Examples

Show connected hosts

capa auth

Sign in to GitHub.com

capa auth github.com

Sign in to GitLab.com

capa auth gitlab.com

After authentication succeeds for a host, you can use CAPA workflows that clone or access private repos on that host (for example skill sources that require credentials).

Token Refresh Behavior

CAPA automatically refreshes OAuth tokens in the background. As of v1.9.2, transient refresh failures (server errors, network issues, rate limits) preserve existing tokens instead of deleting them. Only permanent failures (invalid_grant, invalid_token, explicit revocation) trigger token removal. This means brief provider outages will not force re-authentication.

Exit codes and failures

  • Server startup failure terminates with a non-zero exit after closing the database handle.
  • Invalid provider hostname, unsupported host (anything other than github.com or gitlab.com for this command), OAuth start errors, or authentication timeout/non-completion exit with an error message and non-zero status.