Projects

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.

Manage your GitScrum projects without leaving the terminal.

Commands

List Projects

View all accessible projects:

gitscrum project list

Output:

📦 Your Projects

┌────────────────────────────────────────────────────────────┐
│ acme-dashboard         │ Active  │ 23 tasks │ Sprint 15   │
│ mobile-app             │ Active  │ 45 tasks │ Sprint 12   │
│ api-v2                 │ Active  │ 18 tasks │ Sprint 8    │
│ legacy-refactor        │ Paused  │ 67 tasks │ Sprint 3    │
└────────────────────────────────────────────────────────────┘

4 projects

Filter Projects

# Active projects only
gitscrum project list --status active

# By team
gitscrum project list --team backend

# Search by name
gitscrum project list --search "dashboard"

Compact View

gitscrum project list --compact

Output:

acme-dashboard (23) mobile-app (45) api-v2 (18) legacy-refactor (67)

Current Project

Show the project linked to your current directory:

gitscrum project current

Output:

📦 Current Project: acme-dashboard

ID:          prj_abc123
Status:      Active
Team:        Product Team
Sprint:      Sprint 15 (Feb 3 - Feb 14)
Tasks:       23 open, 45 completed
Repository:  github.com/acme/dashboard

Detection Priority

1. .gitscrum.yml in current directory
2. .gitscrum.yml in parent directories
3. Git remote matching linked repository
4. Global config default project

Switch Projects

Change the active project:

gitscrum project switch

Interactive selection:

? Select project:
  ❯ acme-dashboard (current)
    mobile-app
    api-v2
    legacy-refactor

Direct Switch

gitscrum project switch acme-dashboard
gitscrum project switch prj_abc123  # By ID

Temporary Switch

Use a different project for one command:

gitscrum task list --project mobile-app

Project Info

View detailed project information:

gitscrum project info acme-dashboard

Output:

📦 acme-dashboard

General
───────
ID:          prj_abc123
Name:        Acme Dashboard
Description: Internal analytics dashboard
Status:      Active
Created:     Jan 15, 2025
Owner:       @sarah.dev

Team
────
Members:     8
Lead:        @john.dev
Teams:       Backend (4), Frontend (3), Design (1)

Sprint
──────
Current:     Sprint 15 (Feb 3 - Feb 14)
Velocity:    45 points/sprint
Burndown:    https://studio.gitscrum.com/p/acme-dashboard/sprint

Tasks
─────
Open:        23 (12 in progress, 11 todo)
Completed:   45
Blocked:     2

Repositories
────────────
• github.com/acme/dashboard (primary)
• github.com/acme/dashboard-api

Create Project

Create a new project:

gitscrum project create "API v3"

Interactive setup:

? Project name: API v3
? Project key: API (used for task IDs like API-123)
? Description: Next generation API with GraphQL
? Team: Backend Team

✓ Project "API v3" created
  ID: prj_xyz789
  URL: https://studio.gitscrum.com/p/api-v3

With Options

gitscrum project create "API v3" \
  --key API \
  --description "Next generation API" \
  --team backend \
  --template scrum

Templates

Available templates:

Archive Project

Archive a completed or paused project:

gitscrum project archive legacy-refactor

⚠️  Archive "legacy-refactor"?

This will:
• Hide from active project list
• Preserve all tasks and history
• Stop sprint automation

Archived projects can be restored anytime.

? Continue: Yes

✓ Project archived

Restore Project

gitscrum project restore legacy-refactor

Project Settings

View project settings:

gitscrum project settings

Output:

⚙️  Project Settings: acme-dashboard

General
───────
Time tracking:     Required
Default sprint:    2 weeks
Task prefix:       DASH

Automations
───────────
Auto-assign:       On branch create
Timer auto-start:  On task transition
Sprint rollover:   Incomplete tasks

Integrations
────────────
GitHub:            connected
Slack:             #acme-dashboard

Update Settings

# Enable/disable features
gitscrum project settings --time-tracking required
gitscrum project settings --auto-assign enabled

# Sprint configuration
gitscrum project settings --sprint-length 2w
gitscrum project settings --sprint-rollover enabled

Repository Management

Link repositories to projects:

gitscrum project link-repo github.com/acme/new-repo

✓ Repository linked to acme-dashboard
  Branch detection: enabled
  Commit tracking: enabled

List Linked Repositories

gitscrum project repos

📂 Linked Repositories

• github.com/acme/dashboard (primary)
• github.com/acme/dashboard-api
• github.com/acme/dashboard-mobile

Unlink Repository

gitscrum project unlink-repo github.com/acme/old-repo

Team Members

View project team:

gitscrum project members

Output:

👥 Project Members: acme-dashboard

Owner
─────
@sarah.dev (Admin)

Backend Team
────────────
@john.dev (Lead)
@alex.dev
@mike.dev
@lisa.dev

Frontend Team
─────────────
@chris.dev (Lead)
@emma.dev
@david.dev

Design
──────
@nina.design

Add Members

gitscrum project add-member alex@company.com --role developer
gitscrum project add-member team@company.com --role viewer

Remove Members

gitscrum project remove-member alex@company.com

Project Stats

Quick project statistics:

gitscrum project stats

Output:

📊 acme-dashboard - Last 30 Days

Tasks
─────
Created:     34
Completed:   28
In Progress: 12
Velocity:    47 pts/sprint

Time
────
Logged:      156h 23m
Avg/task:    4h 12m

Team
────
Active:      8 members
Top:         @john.dev (42h)

Date Range

gitscrum project stats --since "last month"
gitscrum project stats --since 2026-01-01 --until 2026-01-31

JSON Output

gitscrum project list --format json

{
  "projects": [
    {
      "id": "prj_abc123",
      "name": "acme-dashboard",
      "key": "DASH",
      "status": "active",
      "tasks": {
        "open": 23,
        "completed": 45
      },
      "current_sprint": {
        "name": "Sprint 15",
        "ends_at": "2026-02-14"
      }
    }
  ]
}

Environment Variables

Override project detection:

export GITSCRUM_PROJECT="api-v2"
gitscrum task list  # Uses api-v2 regardless of directory

Useful in CI/CD or when working outside a repository.

Aliases

Create shortcuts for frequently used projects:

# ~/.gitscrum/config.yml
aliases:
  dash: acme-dashboard
  api: api-v2
  app: mobile-app

Usage:

gitscrum project switch dash
gitscrum task list --project api