| name | vertical |
| description | Manage projects with the Vertical board using the itsvertical CLI. Create projects, add tasks, organize boxes, split layers, and track progress. Use when the user mentions Vertical, project management, boxes, slices, .vertical files, or itsvertical. |
Vertical
File-based project management with vertical slicing. The CLI command is itsvertical (npm package: itsvertical).
Setup
Before using any commands, check if itsvertical is available:
itsvertical --version
If not found, install it globally:
npm install -g itsvertical
Core Workflow
When working on a task, always read its notes first with itsvertical task notes <file> <task-id>. Notes contain important context, requirements, and decisions about the work.
Every Vertical project follows this pattern:
itsvertical new project.vertical "Project Name"
itsvertical show project.vertical
itsvertical box rename project.vertical <id> "Box Name"
itsvertical task add project.vertical <layer-id> "Task name"
itsvertical task done project.vertical <task-id>
itsvertical project.vertical
The new and open commands automatically track boards in ~/.vertical/history.json. Use itsvertical history list to find all known boards.
Key Concepts
- Project: a single
.vertical file containing the full board state
- Boxes (slices): 9 boxes numbered 1-9. Each represents a vertical slice of work.
- Layers: steps within a box. A box starts with one layer. Split to create phases (e.g., "Design" then "Build").
- Tasks: work items within a layer. Can be marked done, renamed, moved, reordered. Each task can have rich text notes (
notesHtml).
All Commands
All entities are addressed by UUID. Use itsvertical show to get IDs. Every command accepts --json to output the full board state as JSON.
Project
itsvertical <file>
itsvertical new <path> <name>
itsvertical show <file>
itsvertical show <file> --json
itsvertical show <file> --box <slice-id>
itsvertical show <file> --visual
itsvertical rename <file> <name>
itsvertical open <file>
History
itsvertical history list
itsvertical history list --json
itsvertical history add <file>
itsvertical history remove <name-or-file>
Tasks
itsvertical task add <file> <layer-id> <name>
itsvertical task add <file> <layer-id> <name> --after <task-id>
itsvertical task done <file> <task-id>
itsvertical task undone <file> <task-id>
itsvertical task rename <file> <task-id> <name>
itsvertical task delete <file> <task-id>
itsvertical task move <file> <task-id> <layer-id>
itsvertical task notes <file> <task-id>
itsvertical task notes <file> <task-id> --set <html>
itsvertical task notes <file> <task-id> --clear
Boxes
itsvertical box rename <file> <slice-id> <name>
itsvertical box clear <file> <slice-id>
itsvertical box swap <file> <id-1> <id-2>
Layers
itsvertical layer split <file> <task-id>
itsvertical layer merge <file> <layer-id>
itsvertical layer rename <file> <layer-id> <name>
itsvertical layer clear <file> <layer-id>
itsvertical layer status <file> <layer-id> done
itsvertical layer status <file> <layer-id> none
Common Patterns
Set up a project with named boxes
itsvertical new project.vertical "Online Course Platform"
itsvertical show project.vertical
itsvertical box rename project.vertical <id1> "Course Catalog"
itsvertical box rename project.vertical <id2> "Video Player"
itsvertical box rename project.vertical <id3> "Progress Tracking"
Add tasks to a box
itsvertical show project.vertical --box <slice-id>
itsvertical task add project.vertical <layer-id> "Create mockups"
itsvertical task add project.vertical <layer-id> "Review with team"
itsvertical task add project.vertical <layer-id> "Finalize design"
Split a box into phases
itsvertical layer split project.vertical <review-task-id>
itsvertical layer rename project.vertical <first-layer-id> "Draft"
itsvertical layer rename project.vertical <new-layer-id> "Polish"
Track progress with --json
itsvertical show project.vertical --json
The JSON output contains the full board: project, slices (sorted by boxNumber), layers, and tasks with all IDs.
View the board as a grid
itsvertical show project.vertical --visual
The grid shows all 9 boxes with their tasks, layer structure, and a summary table — useful for a quick overview without opening the browser UI.
Move a task between boxes
itsvertical task move project.vertical <task-id> <target-layer-id>
Error Handling
When --json is passed, errors output as {"error": "..."} instead of plain text. Without --json, errors print to stderr as Error: ....
Anti-Patterns
- Don't hardcode IDs — always get fresh IDs from
itsvertical show before operating on entities.
- Don't forget --json for scripting — the human-readable output format is not stable; use
--json for reliable parsing.
- Don't use
open (or the itsvertical <file> shorthand) in automated workflows — it starts a browser server meant for human interaction. Use the other commands for agent work.
