CLI Reference

Complete technical reference for the agentodo command-line interface. Control AgenToDo from any terminal with full access to tasks, projects, and perspectives.

Installation

The agentodo CLI ships inside AgenToDo.app and requires no separate installation. It's located at:

/Applications/AgenToDo.app/Contents/Resources/bin/agentodo

Add to PATH

For convenient access from any terminal, add the CLI to your shell's PATH:

export PATH="$PATH:/Applications/AgenToDo.app/Contents/Resources/bin"

Add this line to your shell's configuration file (~/.zshrc, ~/.bash_profile, etc.) to make it permanent.

Setup

The CLI requires AgenToDo to have been launched at least once — this registers a background helper (AgenToDoSyncd) that keeps sync flowing when the app is closed and lets the CLI work without the GUI. macOS will ask you to approve it as a Login Item — do that in System Settings → General → Login Items. You can decline, but then sync only runs while AgenToDo is open and the CLI can't reach your data (exit code 5, "daemon unreachable").

Verify Setup

Check that everything is working correctly:

agentodo doctor

This command verifies:

• Daemon is registered and running
• IPC communication is working
• iCloud sync status
• Schema version compatibility

Commands

tasks

Manage individual tasks — the core building blocks of your productivity system.

List Tasks

# List all tasks
agentodo tasks list

# Filter by perspective
agentodo tasks list --due today
agentodo tasks list --tag errands --flagged
agentodo tasks list --project "Launch"

# JSON output for scripting
agentodo tasks list --project "Launch" --json

# Live-updating dashboard (TTY only)
agentodo tasks list --watch

Add Tasks

# Basic task
agentodo tasks add "Buy milk"

# With metadata
agentodo tasks add "Buy milk" --due tomorrow --tag errands
agentodo tasks add "Ship v2" --project "Launch" --flagged --estimate 2h

Task Operations

# Complete/uncomplete
agentodo tasks complete <uuid>
agentodo tasks uncomplete <uuid>

# Edit task
agentodo tasks edit <uuid> --title "New title" --due friday

# Move to project
agentodo tasks move <uuid> --project "Home"

# Delete task
agentodo tasks delete <uuid>

Show Task Details

agentodo tasks show <uuid>
agentodo tasks show <uuid> --json

quickadd

Fast capture with natural language parsing. The quickest way to get thoughts out of your head.

Grammar

Quickadd uses markers to automatically parse metadata:

• #tag — Add tags
• ::project — Assign to project
• ! — Flag as important
• due:today, due:tomorrow, due:YYYY-MM-DD, due:3d, due:2w — Set due dates
• est:30m, est:2h — Time estimates

Escaping

Use backslashes to include literal markers:

• \# for literal # symbols
• \\ for literal backslashes

Examples

# Simple capture
agentodo quickadd "Buy milk due:tomorrow #errands"

# Complex task
agentodo quickadd "Ship v2 ::Launch !est:2h"

# Multiple tags
agentodo quickadd "Call plumber #home #urgent due:today"

# Escaped characters
agentodo quickadd "Tweet about \#AgentToDo launch"

inbox

Manage your capture inbox — the first stop for all new tasks.

Status

# Check inbox count
agentodo inbox status

# JSON format
agentodo inbox status --json

Interactive Triage

# Process inbox items one by one (TTY only)
agentodo inbox process

Interactive mode uses single-key commands:

• n — Next item
• d — Delete current item
• c — Complete current item
• f — Flag current item
• p — Assign to project
• t — Add tag
• q — Quit triage

projects

Organize tasks into projects — collections of related work with clear outcomes.

List Projects

# All projects
agentodo projects list

# JSON output
agentodo projects list --json

Create Projects

# Basic project
agentodo projects add "Launch v2"

# Sequential project (tasks revealed one at a time)
agentodo projects add "Launch v2" --type sequential

# Parallel project (all tasks visible)
agentodo projects add "Launch v2" --type parallel

# Single-action list
agentodo projects add "Errands" --type single-actions

Project Operations

# Show project details
agentodo projects show <uuid>

# Edit project
agentodo projects edit <uuid> --title "New name" --type sequential

# Complete project
agentodo projects complete <uuid>

# Delete project
agentodo projects delete <uuid>

tags

Organize and filter tasks with flexible tagging.

# List all tags
agentodo tags list

# Add new tag
agentodo tags add "urgent"

# Rename tag
agentodo tags rename "urgent" "high-priority"

# Delete tag
agentodo tags delete "high-priority"

folders

Group related projects together for better organization.

# List folders
agentodo folders list

# Add folder
agentodo folders add "Work"

# Rename folder
agentodo folders rename "Work" "Professional"

# Delete folder
agentodo folders delete "Professional"

perspectives

Access the built-in smart views that help you focus on what matters most.

Built-in Perspectives

# List all perspectives
agentodo perspectives list

# Show specific perspective
agentodo perspectives show inbox
agentodo perspectives show today
agentodo perspectives show forecast
agentodo perspectives show flagged
agentodo perspectives show waiting-on
agentodo perspectives show review
agentodo perspectives show completed
agentodo perspectives show calendar
agentodo perspectives show nearby

agent

Trigger AI operations via the command bar engine.

# Trigger AI agent with natural language command
agentodo agent run "Flag all tasks due today and move them to Focus project"

# List recent agent runs
agentodo agent runs

sync

Monitor and control iCloud synchronization.

# Check sync status
agentodo sync

# Force sync trigger
agentodo sync --trigger

doctor

Check that everything is working — connection to AgenToDo, iCloud sync status, and version compatibility.

# Full system check
agentodo doctor

# JSON output for scripting
agentodo doctor --json

Checks include:

• Daemon registration and connectivity
• iCloud account status
• Schema version compatibility
• File permissions and accessibility
• Network connectivity for sync

open

Open specific items in the AgenToDo GUI using deep links.

# Open specific task
agentodo open task <uuid>

# Open specific project
agentodo open project <uuid>

# Open perspectives
agentodo open inbox
agentodo open today
agentodo open flagged

# Quick entry
agentodo open quick-entry

# Location-based activity
agentodo open location/activity

completions

Generate and install shell autocompletions for faster typing.

# Generate completions for your shell
agentodo completions --shell zsh
agentodo completions --shell bash
agentodo completions --shell fish

# Install completions (macOS with Homebrew)
agentodo completions --shell zsh --install

JSON Output

Most commands support structured JSON output for scripting and integration.

Enable JSON Mode

Use either method:

# Command-line flag
agentodo tasks list --json

# Environment variable
AGENTODO_JSON=1 agentodo tasks list

Output Format

• Lists: NDJSON (newline-delimited JSON) — one object per line
• Single items: Single JSON object
• Field names: snake_case convention

Schema Versioning

Check the current schema version for compatibility:

agentodo doctor --json | jq .schema_version

Exit Codes

The CLI uses standard Unix exit codes for scripting and automation:

Code	Meaning	Description
0	Success	Operation completed successfully
1	Generic error	General failure or invalid usage
2	Not found	Requested item (task, project, etc.) doesn't exist
3	Invalid argument	Invalid parameter or option value
4	Not supported	Operation requires the app to be open
5	Daemon unreachable	Can't connect to AgenToDo — launch the app first

Environment Variables

Control CLI behavior with environment variables:

AGENTODO_JSON

Enable JSON output mode globally:

export AGENTODO_JSON=1
agentodo tasks list  # Outputs JSON

AGENTODO_NO_COLOR / NO_COLOR

Disable colored output for piping or accessibility:

export AGENTODO_NO_COLOR=1
# or
export NO_COLOR=1

Deep Link URL Scheme

AgenToDo supports a custom URL scheme for deep linking from external apps and scripts.

URL Format

# Tasks and projects
agentodo://task/<UUID>
agentodo://project/<UUID>

# Perspectives
agentodo://inbox
agentodo://today
agentodo://flagged
agentodo://review

# Quick entry
agentodo://quick-entry

# Location-based
agentodo://location/activity

Usage Examples

# Open URL from command line
open "agentodo://today"

# Embed in scripts or other apps
echo "agentodo://task/$(agentodo quickadd 'Follow up' --json | jq -r .id)"

Scripting Patterns

Common automation patterns using the CLI in shell scripts and workflows.

JSON Processing with jq

# Get all flagged tasks due today
agentodo tasks list --flagged --due today --json | \
  jq '.[] | select(.due_date == "2026-05-27") | .title'

# Count tasks by project
agentodo tasks list --json | \
  jq -r '.project_title // "Inbox"' | \
  sort | uniq -c | sort -rn

Batch Operations with xargs

# Complete all tasks tagged "quick"
agentodo tasks list --tag quick --json | \
  jq -r '.id' | \
  xargs -I  agentodo tasks complete 

# Move all overdue tasks to "Review" project
agentodo tasks list --overdue --json | \
  jq -r '.id' | \
  xargs -I  agentodo tasks move  --project "Review"

Shell Script Example

#!/bin/bash
# Daily task summary script

echo "📋 Daily Task Summary - $(date +%Y-%m-%d)"
echo "================================="

# Inbox count
inbox_count=$(agentodo inbox status --json | jq -r '.count')
echo "📥 Inbox: $inbox_count tasks"

# Today's tasks
today_count=$(agentodo tasks list --due today --json | wc -l)
echo "📅 Due Today: $today_count tasks"

# Flagged tasks
flagged_count=$(agentodo tasks list --flagged --json | wc -l)
echo "🚩 Flagged: $flagged_count tasks"

# Overdue tasks
overdue_count=$(agentodo tasks list --overdue --json | wc -l)
if [ $overdue_count -gt 0 ]; then
    echo "⚠️  Overdue: $overdue_count tasks"
fi

echo ""
echo "🎯 Focus: Run 'agentodo open today' to get started"