roadmap-cli 1.0.0

Enterprise-grade command line tool for project roadmap management with GitHub integration, data visualization, and advanced analytics

Roadmap CLI

Project Management as Code — Manage your project in git, not in a tool.

Roadmap is a CLI-first project management tool designed for developers who want to keep their project data in git, not locked away in another SaaS tool. If you use git, shell scripts, and plain text files, Roadmap feels like home.

The Problem

Modern project management tools solve a problem developers don't have:

• You already track work in git. Commit messages, PRs, issues in GitHub/GitLab... it's all there.
• You duplicate effort. Update status in Jira, then mention it in Slack, then close the GitHub issue. Same information, three places.
• You can't script your workflow. Want to auto-assign issues based on a commit? Good luck with most tools.
• Your data lives elsewhere. Offline? Can't access your roadmap. Switching tools? Export is painful.

The Solution

Roadmap stores your project data in plain YAML + Markdown files tracked in git. This simple approach gives you:

Problem	Solution
Duplicated data entry	Single source of truth: your git repo
Manual status updates	Auto-sync on commits (fixes issue-123)
No offline access	Clone the repo, work offline, push changes
Vendor lock-in	Files stay plain text forever
Non-scriptable workflow	Composable with jq, fzf, ripgrep, shell scripts
Missing context	Full git history + blame for every change
Team bloat for small teams	Start solo, scale to teams without learning new tool

Project management as a durable, automatable, self-owned system — not a product you rent.

Why It Works for Small Teams

For Solo Developers

roadmap today                    # What am I working on?
roadmap issue update 42 done     # Mark issue done
git log --oneline                # See what I shipped

No UI to load. No notifications to ignore. Just you, your terminal, and your git history.

For Small Teams (3-8 people)

roadmap issue list --filter assignee=alice
roadmap milestone list --project web-app
git push && roadmap sync github   # Two-way sync with GitHub

Everyone sees the same data (it's in git). Changes are trackable (git blame). Decisions are documented (commits). No meetings about "where is the roadmap file?"

For Distributed Teams

roadmap issue create "API pagination" --assignee bob --milestone sprint-2
# Bob works offline, commits changes locally
# Roadmap auto-updates via commit message: git commit -m "fixes API pagination"
git pull                         # Everyone syncs to latest
roadmap sync github              # GitHub issues stay in sync

Git is the synchronization layer. No merge conflicts on simple status changes. No "who has the lock?"

Key Features

📋 Issue Management

• Create, list, update, delete issues
• Status tracking (todo, in-progress, blocked, review, done)
• Priority levels (low, medium, high, critical)
• Team assignment and filtering
• Advanced search and sorting

📅 Milestone Planning

• Create sprints/releases as milestones
• Track progress (how many issues done?)
• Due dates and scope management
• Link issues to milestones

🚀 Roadmap Planning

• High-level quarterly/annual plans
• Organize milestones by roadmap
• Strategic tracking

🔗 Git Integration

• Auto-sync on commit: git commit -m "fixes issue-42" → issue status updates
• Two-way GitHub sync: Pull requests → issues, status changes → PR labels
• Commit blame: See who changed what and when

📊 Output Formats

roadmap today                    # Rich (interactive)
roadmap today --format json      # JSON (for scripting)
roadmap today --format csv       # CSV (for spreadsheets)
roadmap today --format plain     # Plain text (for pipes)

Composable with Unix tools:

roadmap issue list --format json | jq '.[] | select(.priority == "critical")'
roadmap today --format csv | fzf --preview 'cat {}'
roadmap issue list --format plain | grep -i "performance"

🔐 Secure by Default

• Data stored locally (or in git)
• No cloud account required
• Git history = audit trail
• Credentials managed via system keyring
• Open source (audit the code)

Installation

Recommended: Poetry or uv

Poetry (recommended for projects):

poetry add roadmap-cli

uv (fast, lightweight):

uv tool install roadmap-cli

Pip (simple)

pip install roadmap-cli

From Source

git clone https://github.com/shanemiller/roadmap.git
cd roadmap
poetry install
poetry run roadmap --help

Quick Start (5 minutes)

1. Initialize your project

cd my-project
roadmap init

This creates .roadmap/ directory with configuration.

2. Create an issue

roadmap issue create "Fix login timeout issue"
roadmap issue list

3. Start tracking work

roadmap issue update 1 in-progress
roadmap issue assign 1 alice

4. Auto-sync with git

git commit -m "fixes issue 1: login timeout resolved"
roadmap issue list              # Status auto-updated to 'done'

5. View your priorities

roadmap today                   # Your task list
roadmap today --filter priority=critical

→ Next steps: Read Quick Start Guide for more examples.

Documentation

Guide	For	Time
Quick Start	New users	5 min
Workflows	Real-world patterns	10 min
FAQ	Questions & comparisons	15 min
Architecture	Technical details	20 min
Installation	Setup & troubleshooting	varies
Security	Privacy & safety	10 min
Future Features	Roadmap (v1.1+)	5 min

Compare to Other Tools

Tool	Model	Data	Good For	Bad For Roadmap
Jira	SaaS/On-prem	Proprietary DB	Large enterprises	Small teams, CLI, offline work
Linear	SaaS	Cloud	Growing startups	No offline, no git-native
Trello	SaaS	Cloud	Visual boards	Serious PM, git-less
GitHub Issues	SaaS	GitHub	Open source	Cross-repo, multiple teams
Notion	SaaS	Cloud	Note-taking	Structured workflows
Roadmap	CLI	Git + YAML	Small teams, developers	Enterprise RBAC, web UI (coming v2.0)

See FAQ.md for deeper comparisons.

Scope & Limitations

What Roadmap Does Well

Single Repository:

• Track issues, milestones, and roadmaps within one repo
• Organize work by priority, assignment, and status
• Integrate with git commits via auto-sync
• Export to multiple formats for reporting
• Work offline, sync when ready

Small Teams (1-8 people):

• Everyone has read/write access to the repo
• Git-based synchronization (no merge conflicts on simple status changes)
• All changes are tracked and auditable via git history
• CLI-first workflow matches developer preferences

What Roadmap Doesn't Do

Multiple Repositories:

• This tool is repo-scoped by design (each repo gets its own .roadmap directory)
• If you manage multiple related projects across repos, use:
  • GitHub Projects (free, integrated with repos)
  • Jira or Linear (enterprise, for complex coordination)
  • Your own meta-layer (if you need something custom)
• Each repo runs independently; there's no built-in cross-repo aggregation

Enterprise Features:

• Complex RBAC (role-based access control)
• Multiple teams with separate permissions
• Audit logging and compliance reporting
• Web UI and mobile access
• SaaS infrastructure

For these, use Jira, Linear, or GitHub Enterprise.

Why This Scope?

Roadmap intentionally stays small because:

1. It solves the actual problem for solo devs and small teams (duplicate data entry)
2. Larger teams benefit from better tools (Jira, Linear) that solve different problems
3. Git as the sync layer works at scale up to ~5 projects per person
4. Simplicity is a feature — less code = fewer bugs = easier to fork/modify

Future-Proofing

The schema includes optional repo_url (on projects) and project_id (on milestones) fields for future tooling that might aggregate across repos. These fields are unused today but allow extensions without breaking existing data.

Real-World Example

Solo Developer

# Monday: Plan sprint
roadmap milestone create sprint-12 --due 2025-02-14
roadmap issue create "Refactor auth module" --milestone sprint-12 --priority high

# Wednesday: Work offline
git clone . ~/offline
cd ~/offline
# ... code ...
git commit -m "refactors auth module, fixes security issue"
roadmap issue status 42 done   # Mark done

# Friday: Sync and review
git push
roadmap today --done            # See what shipped
roadmap sync github             # Update GitHub labels

Small Team (PM + 3 devs)

# Monday standup (async in Slack)
roadmap today --format json | jq '.[] | .title' | sort
# → Shows everyone's tasks

# Devs work independently
git commit -m "implements new API endpoint [closes roadmap:issue-58]"
roadmap sync github             # PR gets linked to issue

# Friday metrics
roadmap analysis velocity sprint-12    # How many issues completed?

See Workflows.md for more patterns.

Integrations

Works Well With

CLI Tools:

• jq — Query issues as JSON
• fzf — Fuzzy find issues
• ripgrep — Search issue descriptions
• Standard Unix: grep, awk, sed, sort, uniq

Development:

• Git hooks (auto-sync on commit)
• GitHub/GitLab (two-way sync)
• CI/CD (create issues on test failures)
• Cron jobs (daily snapshots, reminders)

Data:

• Spreadsheets (export to CSV)
• Grafana (stream metrics)
• Slack (notify on updates)

See Workflows.md for integration examples.

Philosophy

• Plain text first. Data lives in YAML + Markdown, tracked in git.
• CLI-native. Full power from your terminal. No bloated UI.
• Offline by default. Clone repo, work anywhere, push changes.
• Git is your database. History, blame, and rollback come free.
• Composable. Works with jq, shell scripts, and Unix tools.
• Developer-friendly. Made by developers, for developers.

Getting Help

• Questions? See FAQ.md
• Getting started? See Quick Start
• Ideas? See Future Features
• Bugs? Report on GitHub
• Contributing? Join us! (coming soon)

License

License.md — MIT

---

Ready to stop duplicating your work? Get started in 5 minutes →