Installing the `pillar` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install pillar-cli

It will make the pillar command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall pillar-cli uninstalls.

Back to the crate overview.

Readme

Pillar

A file-based task tracker for managing projects, milestones, and issues

Pillar is a command-line task tracker that uses plain text files (Markdown with YAML frontmatter) to manage your projects, milestones, and issues. Perfect for developers who want to track work without leaving the terminal or dealing with complex web interfaces.

✨ Features

📁 File-based: All data stored as Markdown files in your repository
🎯 Project Management: Organize work into projects, milestones, and issues
💬 Comments: Add timestamped comments to any entity
🏷️ Flexible Filtering: Filter by status, priority, tags, and more
📊 Kanban Board: Visualize work across status columns
🌐 Web UI: Launch a premium local dashboard with pillar ui
🤖 Agent-Friendly: Designed for AI coding agents with a clean CLI and Markdown-first structure
🔍 Status Overview: Get a quick snapshot of all active work
⚙️ Configurable: Separate PM data from code with base directory support
🚀 No Database: Git-friendly plain text files

🚀 Quick Start

# Initialize a new workspace
pillar init

# Create a project
pillar project create "MyApp" --priority high

# Add a milestone
pillar milestone create MyApp "v1.0" --date 2026-03-01

# Create an issue
pillar issue create MyApp "Fix login bug" --priority urgent --milestone "v1.0"

# View board
pillar board

# Launch Web UI
pillar ui

# Add a comment
pillar comment add issue MyApp 1 "Working on this now"

📦 Installation

From Crates.io (Recommended)

cargo install pillar-cli

From Source

git clone https://github.com/nqn/pillar.git
cd pillar
cargo install --path .

Homebrew (Coming Soon)

brew install pillar

📖 Usage

Initialize a Workspace

# Standard initialization (stores data in current directory)
pillar init

# Use a base directory (keeps PM data separate from code)
pillar init --path pm

Managing Projects

# Create a project
pillar project create "MyProject" --priority medium

# List all projects
pillar project list

# Filter projects
pillar project list --status in-progress --priority high

# Show project details
pillar project show "MyProject"

# Update project
pillar project edit "MyProject" --status in-progress --priority high

Managing Milestones

# Create a milestone
pillar milestone create MyProject "v1.0" --date 2026-06-01

# List milestones
pillar milestone list

# Filter by project
pillar milestone list --project MyProject

# Update milestone
pillar milestone edit MyProject "v1.0" --status in-progress

Managing Issues

# Create an issue
pillar issue create MyProject "Add user authentication" \
  --priority high \
  --milestone "v1.0" \
  --tags "feature,security"

# List issues
pillar issue list

# Filter issues
pillar issue list --status todo --priority high --project MyProject

# Update issue
pillar issue edit MyProject/001 --status in-progress

Comments

# Add comment to project
pillar comment add project MyProject "Sprint planning completed"

# Add comment to issue
pillar comment add issue MyProject 1 "Fixed in commit abc123"

# Add comment to milestone
pillar comment add milestone MyProject "v1.0" "All features complete"

# List comments
pillar comment list project MyProject
pillar comment list issue MyProject 1

Viewing Status

# Overview of all work
pillar status

# Kanban board view
pillar board

# Board for specific project
pillar board MyProject

### Web UI

Launch the interactive local dashboard:

```bash
pillar ui
# or specify a custom port
pillar ui --port 8080

📂 File Structure

When you run pillar init, it creates the following structure:

.pillar/
├── config.toml           # Workspace configuration
└── templates/            # Templates for new entities
    ├── project.md
    ├── milestone.md
    └── issue.md

MyProject/                # Project directory
├── README.md             # Project metadata and description
├── milestones/           # Milestone files
│   └── v1.0.md
└── issues/               # Issue files
    ├── 001-add-auth.md
    └── 002-fix-bug.md

Example Issue File

---
title: Add user authentication
status: in-progress
priority: high
project: MyProject
milestone: v1.0
tags: [feature, security]
created: 2025-12-29T10:00:00Z
---

# Add user authentication

## Description

Implement OAuth2 authentication for user login.

## Acceptance Criteria

- [ ] OAuth2 integration
- [ ] Session management
- [ ] Logout functionality

## Comments

### [2025-12-29T14:30:00Z] - Alice
Started implementation, using passport.js

### [2025-12-29T16:45:00Z] - Bob
Added tests for auth flow

🎯 Status Values

backlog - Not yet prioritized
todo - Ready to work on
in-progress - Currently being worked on
completed - Finished
cancelled - Not doing this

🔥 Priority Levels

low - Nice to have
medium - Standard priority
high - Important
urgent - Critical, needs immediate attention

🔧 Configuration

Base Directory

Keep your PM data separate from code:

# Initialize with base directory
pillar init --path pm

# Now all projects go in ./pm/ directory
pillar project create "MyProject"
# Creates: pm/MyProject/

The configuration is stored in .pillar/config.toml:

[workspace]
version = "0.1.0"
base_directory = "pm"

[defaults]
priority = "medium"
status = "backlog"

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Development Setup

# Clone the repository
git clone https://github.com/nqn/pillar.git
cd pillar

# Run tests (single-threaded to avoid race conditions)
make test

# Build debug binary
make build

# Build release (Bundles UI assets automatically)
make release

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by tools like Linear, Jira, and GitHub Issues
Built with Rust and clap
Follows the Keep a Changelog format

🤖 Agentic Development

Pillar is uniquely positioned for Agentic Development. Because it uses plain Markdown files and a structured CLI, it is the perfect tool for AI coding agents (like GitHub Copilot, Cursor, or specialized agents) to track their own progress.

Clean CLI: Easy for agents to discover and execute commands.
Markdown Context: Agents can read the entire project history and current status directly from the file system.
System Prompts: Provide a clear "contract" for how agents should manage tasks.

Check out the Agent Guide for a ready-to-use system prompt for your AI agents.

📊 Why Pillar?

Git-Friendly: All your tasks are in plain text files that can be versioned with Git. No more losing task history or dealing with database backups.

Developer-Focused: Designed for developers who live in the terminal. No context switching to a web browser.

Portable: Your data is just Markdown files. Easy to read, easy to edit, easy to migrate.

Flexible: Works with your workflow. Use it alongside code, keep it separate, or integrate it into your documentation.

💡 Use Cases

Solo Developers: Track personal projects and TODOs
Small Teams: Collaborate using Git for task management
Open Source: Manage issues alongside code in the same repository
Documentation: Tasks embedded in your documentation site
Offline Work: No internet required, everything is local

🐛 Bug Reports & Feature Requests

Found a bug? Have an idea for a feature? Please open an issue!

⭐ Show Your Support

If you find Pillar useful, please consider:

Giving it a star on GitHub
Sharing it with others
Contributing to the project
Reporting bugs or suggesting features

Installing the pillar executable

Installing the `pillar` executable