majiayu000 SIMBL CLI Guide
Complete command reference for SIMBL, the CLI backlog manager.
Installation
npm install -g simbl
# or
bun install -g simbl
Initialize in a Project
simbl init
Creates .simbl/tasks.md with # Backlog and # Done sections.
Core Commands
Adding Tasks
simbl add "Task title"
simbl add "Task title" --priority 2
simbl add "Task title" --tags "backend,api"
simbl add "Task title" --content "Description here"
simbl add "Task title" --priority 2 --tags "backend,api" --content "Description here"
Listing Tasks
simbl list # All backlog tasks
simbl list --status in-progress # Only in-progress
simbl list --status done # Completed tasks
simbl list --tag backend # Filter by tag
simbl list --project auth # Filter by project
simbl list --search "login" # Search titles/content
simbl list --limit 5 # Limit results
Viewing a Task
simbl show task-1
simbl show 1 # Short form (digits only)
Note: Any command accepting a task ID supports short form. If user provides just digits (e.g., "9"), treat as "task-9" (or "{prefix}-9" with custom prefix).
Updating Tasks
simbl update task-1 --title "New title"
simbl update task-1 --content "Replace content"
simbl update task-1 --append "Add to content"
Managing Tags
simbl tag add task-1 backend
simbl tag add task-1 p1 # Sets priority (replaces existing)
simbl tag add task-1 in-progress # Marks as in-progress
simbl tag remove task-1 backend
Completing Tasks
simbl done task-1 # Move to Done section
Canceling Tasks
simbl cancel task-1 # Adds [canceled] tag
Relationships
simbl relate task-2 --parent task-1 # task-2 is child of task-1
simbl relate task-3 --depends-on task-2 # task-3 depends on task-2
simbl unrelate task-2 --parent # Remove parent relationship
simbl unrelate task-3 --depends-on task-2 # Remove dependency
Validation
simbl doctor # Check for issues
Web UI
simbl serve # Start browser UI on port 3497
Tag Reference
Priority Tags
[p1]- Highest priority (urgent/critical)[p2]- High priority[p3]- Medium-high priority[p4]- Medium priority[p5]- Medium-low priority[p6]- Low priority[p7]- Lower priority[p8]- Very low priority[p9]- Lowest priority
Only one priority tag per task. Adding a new priority replaces the existing one.
Status Tags
[in-progress]- Currently being worked on[canceled]- Task was canceled[refined]- Task has been refined/detailed
Project Tags
[project:name]- Associates task with a project
Relationship Tags
[child-of-task-1]- This task is a subtask of task-1[depends-on-task-2]- This task is blocked by task-2
Custom Tags
Any other [tag-name] format for categorization.
Task File Format
Tasks are stored in .simbl/tasks.md:
# Backlog
## task-1 Implement user authentication
[p2] [backend] [project:auth]
### Description
Add JWT-based auth to the API.
### Acceptance Criteria
- [ ] Login endpoint works
- [ ] Token refresh works
## task-2 Fix null pointer bug
[p1] [in-progress] [depends-on-task-1]
### Description
UserService.getProfile() crashes on null user.
# Done
## task-0 Set up project structure
[p2] [backend]
### Description
Initial project scaffolding.
Multi-line Content
Use quotes for multi-line content:
simbl add "Task title" --content "Line 1
Line 2
Line 3"
simbl update task-1 --append "### Notes
- Point 1
- Point 2"
Common Mistakes
Wrong flags/commands
| ❌ Wrong | ✅ Correct |
|---|---|
--description |
--content |
simbl edit |
simbl update |
simbl modify |
simbl update |
Relationship syntax (flags required, not positional)
# ❌ Wrong - positional args don't work
simbl relate task-2 depends-on task-1
# ✅ Correct - use flag syntax
simbl relate task-2 --depends-on task-1
simbl relate task-2 --parent task-1
Available flags reference
simbl add:
--priority <N>- Set priority (1-9)--tags "tag1,tag2"- Add tags (comma-separated)--content "..."- Set description/content
simbl update:
--title "..."- Replace title--content "..."- Replace content--append "..."- Add to existing content
simbl relate:
--depends-on <id>- This task depends on another--parent <id>- This task is a subtask of another