CLI Overview

⚠️ 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.

GitScrum CLI gives you full access to your GitScrum workspace from the terminal. Everything you do in the web app — creating tasks, tracking time, managing sprints, generating reports — you can do faster from the command line.

No context switching. No browser tabs. Just you, your code, and your terminal.

# Your morning in 30 seconds
$ gitscrum tasks
CODE      TITLE                              STATUS         EFFORT
GS-1234   Implement OAuth flow               In Progress    5 pts
GS-1198   Fix pagination bug                 Todo           2 pts
GS-1201   Add caching layer                  Blocked        8 pts

$ gitscrum timer start GS-1234
Timer started for GS-1234 at 09:15

# ... 3 hours of deep work ...

$ gitscrum timer stop
Logged 3h 12m to GS-1234
  Total today: 5h 45m

$ gitscrum sprints burndown
Sprint 12 — Day 7 of 10
52 │●
40 │  ●──●
30 │       ●──●
20 │            ●  ← You are here
10 │
 0 └─────────────────
    M  T  W  T  F

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

Why CLI?

Stay in Flow

You're debugging a critical issue. You find the bug. Now you need to update the task status and log your time.

Without CLI: Switch to browser → find the tab → navigate to the task → click edit → update status → save → navigate to time tracking → log time.

With CLI: gitscrum tasks update GS-1234 --status done && gitscrum timer stop. Done. Back to coding.

Git-Aware Intelligence

The CLI reads your branch names. When you're on feature/GS-1234-oauth-flow, the CLI knows you're working on GS-1234. Start a timer without specifying a task. View task details without typing the code. It just works.

$ git checkout feature/GS-1234-oauth-flow
$ gitscrum timer start
Timer started for GS-1234 at 09:00

$ gitscrum tasks current
GS-1234: Implement OAuth flow
Status: In Progress | Sprint: Sprint 12 | Effort: 5 pts

CI/CD Native

The CLI is designed for automation. JSON output for scripting. Environment variable authentication for pipelines. Native integrations for GitHub Actions, GitLab CI, and Bitbucket Pipelines.

# GitHub Actions: Update task status on PR merge
- name: Complete task
  run: |
    TASK=$(echo "${{ github.head_ref }}" | grep -oE '[A-Z]+-[0-9]+')
    gitscrum tasks update $TASK --status done

Single Binary, Zero Dependencies

Download. Run. That's it. The CLI is a single Go binary with no runtime dependencies. Works on macOS, Linux, and Windows.

Command Categories

Core Workflows

These are the commands you'll use every day.

Time Tracking

Track every minute. Bill every hour.

Agile Workflows

Sprints, standups, and analytics.

Collaboration

Team communication and documentation.

CRM & Clients (Agency Features)

For agencies managing client work.

Configuration

Set it and forget it.

Real-World Workflow

This is how a typical development session looks with the CLI:

# Morning: See what's on your plate
$ gitscrum tasks
CODE      TITLE                              STATUS
GS-1234   Implement OAuth flow               In Progress
GS-1198   Fix pagination bug                 Todo

# Pick a task and create a branch
$ gitscrum tasks branch GS-1234
Switched to: feature/GS-1234-implement-oauth-flow

# Timer starts automatically (configurable)
$ gitscrum timer
Active: GS-1234 | Running: 45m

# Found a bug while working? Quick ticket creation
$ gitscrum tasks create "Null check missing in OAuth callback" --type bug
Created: GS-1267 - Null check missing in OAuth callback

# End of work: Stop timer and update status
$ gitscrum timer stop
Logged 3h 45m to GS-1234

$ gitscrum tasks update GS-1234 --status "in review"
GS-1234 moved to In Review

# Weekly report? One command
$ gitscrum timer report --week
This Week — 38h 15m across 4 projects

Output Formats

Every command supports multiple output formats:

gitscrum tasks              # Table output (default)
gitscrum tasks --json       # JSON for scripting
gitscrum tasks -q           # Quiet mode (IDs only)
gitscrum tasks --no-color   # Plain text for logs

The --json flag is perfect for piping to jq or integrating with other tools:

# Get all blocked tasks as JSON
$ gitscrum tasks --blocker --json | jq '.[].code'
"GS-1201"
"GS-1156"

Security Model

The CLI is designed around the principle of least privilege.

See Security for the full security model.

Requirements

Next Steps

• Quick Start: Install and authenticate in 2 minutes.
• Configuration: Project configuration with .gitscrum.yml.
• Tasks: Deep dive into task management.
• Timer: Time tracking workflows.
• CI/CD: Automate with GitHub Actions, GitLab CI, and more.