Authentication

Open Source — GitScrum CLI is open source under the MIT license. Available on GitHub and all major package managers. Built for developers — Tasks, timers, sprints, and analytics in your terminal. Git-aware. CI/CD ready.

The GitScrum CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628) for secure, browser-based authentication. This is the same flow used by modern CLI tools like GitHub CLI and Azure CLI.

How It Works

The Device Flow

┌─────────────┐     1. Request code     ┌─────────────┐
│   Terminal  │ ──────────────────────► │  GitScrum   │
│             │ ◄────────────────────── │   OAuth     │
│             │   2. Device code +      │             │
│             │      verification URL   │             │
└─────────────┘                         └─────────────┘
       │                                       ▲
       │ 3. User opens URL                     │
       │    in browser                         │ 5. Validate
       ▼                                       │    login
┌─────────────┐     4. User logs in     ┌─────────────┐
│   Browser   │ ──────────────────────► │  GitScrum   │
│             │                         │   Login     │
└─────────────┘                         └─────────────┘
       │
       │ 6. CLI receives access token
       ▼
┌─────────────┐
│   Terminal  │  ← Authenticated!
└─────────────┘

Why Device Flow?

• No password handling. The CLI never sees your password.
• MFA compatible. Use any 2FA method you have configured.
• Revocable. Revoke CLI access without changing your password.
• Scoped. Tokens have limited permissions.

Login

gitscrum auth login

The CLI displays a code and opens your browser:

Opening browser to complete authentication...

If the browser doesn't open, visit:
  https://gitscrum.com/device

And enter this code:
  ABCD-EFGH

Waiting for authentication...

After you authorize in the browser:

Authentication successful!
Logged in as John Doe (john@example.com)

Check Status

gitscrum auth status

Authenticated: Yes
User:          John Doe (john@example.com)
Workspace:     my-company
Token expires: Feb 15, 2026 09:30 UTC

Who Am I?

gitscrum auth whoami

Logged in as John Doe (john@example.com)

Logout

gitscrum auth logout

This removes stored credentials from ~/.gitscrum/token.json.

Token Storage

OAuth tokens are stored locally:

File permissions are set to 0600 (owner read/write only).

Token Format

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "Bearer",
  "expires_at": "2026-02-15T09:30:00Z"
}

Token Refresh

Access tokens expire after 24 hours. The CLI automatically refreshes tokens using the refresh token. If the refresh token expires (7 days of inactivity), you'll need to auth login again.

CI/CD Authentication

For headless environments (CI/CD pipelines, servers), use environment variable authentication:

export GITSCRUM_ACCESS_TOKEN="your-oauth-access-token"

Obtaining a CI/CD Token

1. Run gitscrum auth login locally
2. Copy the access_token from ~/.gitscrum/token.json
3. Add it as a secret in your CI/CD platform

GitHub Actions

env:
  GITSCRUM_ACCESS_TOKEN: ${{ secrets.GITSCRUM_ACCESS_TOKEN }}

steps:
  - name: Update task
    run: gitscrum tasks update GS-1234 --status done

GitLab CI

variables:
  GITSCRUM_ACCESS_TOKEN: $GITSCRUM_ACCESS_TOKEN

script:
  - gitscrum tasks update GS-1234 --status done

Multiple Accounts

The CLI supports one authenticated user at a time. To switch accounts:

gitscrum auth logout
gitscrum auth login  # Log in as different user

Troubleshooting

Browser Doesn't Open

If the browser doesn't open automatically:

1. Copy the URL from the terminal
2. Paste it into your browser manually
3. Enter the code shown in the terminal

Token Expired

Error: Token expired. Please run: gitscrum auth login

Run gitscrum auth login to re-authenticate.

Behind a Proxy

Set proxy environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

Firewall Issues

The CLI needs HTTPS access to:

• api.gitscrum.com — API requests
• gitscrum.com — OAuth authorization

Ensure these domains are allowed.