# Vertical > 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. - Skill: `seasonedcc/vertical` (Agent Skill) - Install (CLI): `npx skillmds@latest add seasonedcc/vertical` - Raw SKILL.md: https://api.skillmd.com/api/skills/seasonedcc/vertical/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: seasonedcc (https://skillmd.com/u/seasonedcc) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/seasonedcc/vertical --- # 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: ```bash itsvertical --version ``` If not found, install it globally: ```bash npm install -g itsvertical ``` ## Core Workflow When working on a task, always read its notes first with `itsvertical task notes `. Notes contain important context, requirements, and decisions about the work. Every Vertical project follows this pattern: ```bash itsvertical new project.vertical "Project Name" # create a project itsvertical show project.vertical # see the board with IDs itsvertical box rename project.vertical "Box Name" # name a box itsvertical task add project.vertical "Task name" # add tasks itsvertical task done project.vertical # mark done itsvertical project.vertical # view in browser (shorthand for "open") ``` 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 ```bash itsvertical # Shorthand for "open" itsvertical new # Create a new .vertical file itsvertical show # Print board with IDs itsvertical show --json # Output board as JSON itsvertical show --box # Show only one box itsvertical show --visual # Show visual 3x3 grid with summary table itsvertical rename # Rename the project itsvertical open # Open in browser UI ``` ### History ```bash itsvertical history list # List all known boards itsvertical history list --json # List as JSON array itsvertical history add # Manually add a board to history itsvertical history remove # Remove from history (keeps file) ``` ### Tasks ```bash itsvertical task add # Add task to end of layer itsvertical task add --after # Insert after specific task itsvertical task done # Mark as done itsvertical task undone # Mark as not done itsvertical task rename # Rename itsvertical task delete # Delete itsvertical task move # Move to another layer itsvertical task notes # Print task notes itsvertical task notes --set # Set notes (HTML) itsvertical task notes --clear # Clear notes ``` ### Boxes ```bash itsvertical box rename # Rename a box itsvertical box clear # Clear box name itsvertical box swap # Swap two box positions ``` ### Layers ```bash itsvertical layer split # Split at task (tasks after go to new layer) itsvertical layer merge # Merge with next layer itsvertical layer rename # Rename itsvertical layer clear # Clear name itsvertical layer status done # Set status to done itsvertical layer status none # Clear status ``` ## Common Patterns ### Set up a project with named boxes ```bash itsvertical new project.vertical "Online Course Platform" itsvertical show project.vertical # get slice IDs itsvertical box rename project.vertical "Course Catalog" itsvertical box rename project.vertical "Video Player" itsvertical box rename project.vertical "Progress Tracking" ``` ### Add tasks to a box ```bash itsvertical show project.vertical --box # get the layer ID itsvertical task add project.vertical "Create mockups" itsvertical task add project.vertical "Review with team" itsvertical task add project.vertical "Finalize design" ``` ### Split a box into phases ```bash # Split after "Review with team" — tasks after it go to a new layer itsvertical layer split project.vertical itsvertical layer rename project.vertical "Draft" itsvertical layer rename project.vertical "Polish" ``` ### Track progress with --json ```bash # Get structured state for programmatic use 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 ```bash 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 ```bash # Move a task from one box's layer to another box's layer itsvertical task move project.vertical ``` ## 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 ` shorthand) in automated workflows** — it starts a browser server meant for human interaction. Use the other commands for agent work.