Quick Start

⚠️ BETA — GitScrum CLI is in active development. Open source under the MIT license. Available on GitHub. Built for developers — Tasks, timers, sprints, and analytics in your terminal. Git-aware. CI/CD ready.

From zero to managing projects in 2 minutes. Let's go.

Install

One-Line Install (Recommended)

curl -sL https://raw.githubusercontent.com/gitscrum-core/cli/main/install.sh | sh

This downloads the latest release and installs it to /usr/local/bin. Works on macOS and Linux.

macOS (Homebrew)

brew install gitscrum-core/tap/gitscrum

Windows (Scoop)

scoop bucket add gitscrum https://github.com/gitscrum-core/scoop-bucket
scoop install gitscrum

Windows (Chocolatey)

choco install gitscrum

Go Install

If you have Go installed:

go install github.com/gitscrum-core/cli/cmd/gitscrum@latest

Manual Download

Download the binary for your platform from GitHub Releases and add it to your PATH.

Verify Installation

gitscrum --version

You should see something like:

gitscrum version 1.0.0 (go1.21.0)

Authenticate

gitscrum login

This opens your browser to complete OAuth authentication. The flow is:

1. CLI generates a device code
2. Browser opens GitScrum authorization page
3. You log in and authorize the CLI
4. CLI receives access token
5. Token is stored locally in ~/.gitscrum/token.json

No passwords are ever stored or transmitted to third parties.

Verify authentication:

gitscrum status

Logged in as John Doe (john@example.com)
Workspace: my-company
Project: backend-api

Set Defaults

Tell the CLI which workspace and project to use by default:

gitscrum config set workspace my-company
gitscrum config set project backend-api

Now you can run commands without --workspace and --project flags.

First Commands

See Your Tasks

gitscrum tasks

CODE      TITLE                              STATUS         SPRINT
GS-1234   Implement OAuth flow               In Progress    Sprint 12
GS-1198   Fix pagination bug                 Todo           Sprint 12
GS-1156   Add unit tests                     In Review      Sprint 12

Start a Timer

gitscrum timer start GS-1234

Timer started for GS-1234 at 09:15

Stop and Log Time

gitscrum timer stop

Logged 2h 30m to GS-1234
Total today: 4h 15m

Create a Task

gitscrum tasks create -t "Fix memory leak in worker service"

Created: GS-1267 - Fix memory leak in worker service

View Sprint Progress

gitscrum sprints burndown

Sprint 12 Burndown (Day 5 of 10)
50 │●
40 │  ●
30 │    ●───●
20 │          ●
10 │
 0 └──────────────────
     1  2  3  4  5  6

Remaining: 26 pts | Velocity: 5.2 pts/day | On track

Project Configuration

For team projects, create a .gitscrum.yml in your repo root:

gitscrum init -w my-company -p backend-api

This creates:

version: "1"
workspace: my-company
project: backend-api

branch:
  default_prefix: feature
  include_title: true

hooks:
  prepend_task_code: true

Commit this file. Now everyone on your team shares the same defaults.

Shell Completion

Enable tab completion for faster workflows:

Bash

gitscrum completion bash > /etc/bash_completion.d/gitscrum

Zsh

gitscrum completion zsh > "${fpath[1]}/_gitscrum"

Fish

gitscrum completion fish > ~/.config/fish/completions/gitscrum.fish

PowerShell

gitscrum completion powershell >> $PROFILE

What's Next?

• Tasks: Full task management reference
• Timer: Time tracking in depth
• Configuration: All configuration options
• CI/CD: Integrate with your pipelines