Skip to main content

​
Overview

The workflow commands turn Apollo CLI into a developer-first work manager. Start a task and get a git branch automatically. Let urgency scoring tell you what to work on next. Save your favorite filters. Set a default project so you stop typing -p everywhere.
All workflow commands support --json for scripting and Claude Code integration.

​
Task Start / Stop / Current

​
apollo task start <id>

Resolves a task, creates a git branch, marks it in_progress, and tracks your active session. 
# Start by name (fuzzy match)
apollo task start "fix auth bug"

# Start by short ID
apollo task start a1b2c3d4

# Custom branch name
apollo task start "fix auth" --branch "hotfix/auth-fix"

# Skip branch creation
apollo task start "review docs" --no-branch
​
--base
string
default:"main"
Base branch to create from
​
--branch
string
Override the auto-generated branch name
​
--no-branch
boolean
default:"false"
Skip git branch creation, only update task status
What happens:
  1. Generates branch name: feat/<shortId>-<slugified-title>
  2. Creates and checks out the branch (or checks out if it exists)
  3. Stores task metadata as git branch config
  4. Marks task as in_progress in Apollo
  5. Auto-assigns the task to you if unassigned
  6. Stores the active session locally for stop and current

​
apollo task stop [id]

Stops your active session. Stashes uncommitted work, updates status, and shows elapsed time. 
# Stop the current active task
apollo task stop

# Stop and mark as done
apollo task stop --done

# Stop without git stash
apollo task stop --no-stash
​
--done
boolean
default:"false"
Mark the task as done instead of returning to todo
​
--no-stash
boolean
default:"false"
Skip git stash even if there are uncommitted changes

​
apollo task current

Show the currently active task with elapsed time. 
apollo task current
# Working on: Fix authentication bug
#   Project: Apollo
#   Branch:  feat/a1b2c3d4-fix-authentication-bug
#   Elapsed: 1h 23m
#   ID:      a1b2c3d4-...

​
Task Next (Smart Ranking)

​
apollo task next

Shows your highest-priority tasks ranked by a weighted urgency score. Inspired by Taskwarrior’s urgency coefficient system. 
# Show top 5 tasks (default)
apollo task next

# Show top 3 with score breakdown
apollo task next -n 3 --explain

# Scope to a project
apollo task next -p "Apollo"
​
-p, --project
string
Scope to a specific project
​
-n, --count
number
default:"5"
Number of tasks to show
​
--explain
boolean
default:"false"
Show the scoring breakdown for each task

​
Scoring Algorithm

Each task is scored on 6 factors with different weights:
FactorWeightMax RawDescription
Priority4x20critical=20, high=15, medium=10, low=5
Due Date3x20overdue=20, today=18, this week=12, this month=6
Unblocked2x10+10 if no blockers, -20 if blocked
Impact2x20+5 per task you unblock (max 4)
Age1x50-5 based on days since creation
Status1x8in_progress=8, todo=5, blocked=0
The raw score is normalized to 0-100. Use --explain to see the exact breakdown.

​
Saved Filters

Save frequently-used task filter combinations and replay them with a single command.

​
apollo filter save <name>

# Save a filter for high-priority blocked tasks
apollo filter save "my-blockers" --status "blocked" --priority "high,critical" --assignee me

# Save a filter for a project's todo list
apollo filter save "apollo-todo" --project "Apollo" --status "todo"
​
-s, --status
string
Status filter (comma-separated)
​
--priority
string
Priority filter (comma-separated)
​
-a, --assignee
string
Assignee name or me
​
-p, --project
string
Project name
​
--release
string
Release name
​
--unassigned
boolean
Only unassigned tasks
​
--due-before
string
Due before date
​
--limit
string
Max results

​
apollo filter list

apollo filter list
# Name          Flags
# my-blockers   status=blocked, priority=high,critical, assignee=me
# apollo-todo   project=Apollo, status=todo

​
apollo filter run <name>

Replays the saved filter by executing apollo task list with the stored flags. 
apollo filter run "my-blockers"
# Equivalent to: apollo task list --status blocked --priority high,critical --assignee me

​
apollo filter delete <name>

apollo filter delete "my-blockers"
Filters are stored locally in ~/.apollo/apollo-local.json and persist across sessions.

​
Project Context

Set a default project so you don’t need to type -p "ProjectName" on every command.

​
apollo context set <project>

apollo context set "Apollo"
# Default project set to: Apollo
# All commands will use this project unless -p is specified.

​
apollo context show

apollo context show
# Default project: Apollo

​
apollo context clear

apollo context clear
# Default project cleared.
Commands that respect context: task list, release list, epic list, kb list, kb search, kb folders. An explicit -p flag always overrides the context default.

​
Task Dependencies

​
apollo task deps [id]

Visualize a task’s dependency tree — who blocks you and who you unblock. 
# Show deps for a specific task
apollo task deps "fix auth bug"

# Only show upstream blockers
apollo task deps "fix auth" --direction up

# Deeper traversal
apollo task deps "fix auth" --depth 5

# Project-wide dependency chains
apollo task deps --project "Apollo"
​
--direction
string
default:"both"
up (blockers only), down (dependents only), or both
​
--depth
number
default:"3"
Maximum traversal depth
​
-p, --project
string
Show all dependency chains in a project (no task ID needed)
Single task view shows a tree with status icons: 
  Dependencies for: Fix auth bug
  ──────────────────────────────────────────────────

  ▲ Blocks me (upstream):
  │
  └── ✓ Set up OAuth provider done
      └── ○ Configure redirect URLs todo

  ▼ I unblock (downstream):
  │
  ├── ○ Update login page todo
  └── ○ Add SSO support todo
Project-wide view shows linear chains: 
  Dependency chains in Apollo (8 tasks with deps)
  ──────────────────────────────────────────────────

  Chain 1 (3 tasks):
  ✓ Set up OAuth → ● Fix auth bug → ○ Update login page

  Chain 2 (2 tasks):
  ○ Design API schema → ○ Implement REST endpoints