Command Reference

Everything you can do with Task CLI, at a glance.

quick start
# install $ curl -fsSL https://task.simples.media/install.sh | bash # login $ task login Email: you@email.com Code sent! Check your inbox. # start using $ task add "Ship the feature" -p acme -P high Task added: a1b2c3d4

Tasks

task add "title" -p project -P priority -d desc -D due --every recurrence -T tag
Add a new task. Due: tomorrow, friday, +3d, 2026-03-01. Every: daily, weekly, monthly, every 3 days. Tags: repeatable -T medusa -T urgent.
task list -p project -a -m -T tag
List tasks. Use -a to include completed, -m to show only your tasks, -T medusa to filter by tag.
task show id
Show full task details including description.
task start id
Mark a task as in progress.
task hold id
Put a task on hold (waiting on others).
task done id
Mark a task as done.
task reset id
Reset a task back to pending.
task grab id
Assign a task to yourself. Shows assignee in list and board.
task assign id handle|email|alias
Assign a task to someone. Accepts a handle (gule), full email, or local alias. Use none to unassign.
task edit id -t title -p project -P priority -D due --every recurrence -T tag
Edit a task. Only specified fields are updated. Use -D none, --every none, or -T none to clear.
task rm id -f
Remove a task. Use -f to skip confirmation.
task attach id file
Upload a file attachment to a task. Max 5 MB (free) or 25 MB (pro). Files are stored securely in the cloud.
task attach id --list
List all file attachments on a task.
task attach id --get file_id --out path
Download a file attachment. Defaults to current directory if --out not specified.
task attach id --rm file_id
Remove a file attachment from a task.
task screenshot id
Capture a screen area and attach it to a task. Uses native GNOME screenshot UI on Ubuntu, falls back to gnome-screenshot, spectacle, grim+slurp, scrot, or ImageMagick.
task screenshot id -f
Capture full screen and attach. Use -w for active window.

Projects

task project add "name" -a alias
Create a project. Alias auto-generated from name if not provided (e.g. "My App" → my-app).
task project list
List all your projects (owned + shared).
task project edit id -n name -a alias
Rename a project or change its alias.
task project rm id -f
Delete a project and all its tasks. Owner only.

Sharing Pro

task project share project email or @handle
Invite a collaborator by email or @handle. Owner + Pro only.
task project members project
List members and pending invites for a project.
task project remove project email
Remove a collaborator from a project. Owner only.
task project invites
List pending project invitations for you.
task project join project_id
Accept a project invitation.
task project decline project_id
Decline a project invitation.
task project leave project
Leave a shared project. Owner cannot leave.

Profile

Every user has a unique global @handle. Handles work across all teams and machines — assign tasks with just a name, no emails needed.

task profile
Show your handle, email, and plan.
task profile set handle
Set or change your handle. Lowercase, 2-20 chars (a-z 0-9 -). Must be globally unique.

Handles are required — you'll be prompted to choose one on first login or next command. Once set, team members can assign tasks to you with task assign id yourhandle from any machine.

Aliases

Email aliases let you use short names instead of full emails when assigning tasks. Aliases are stored locally and resolved client-side — the API always receives a full email.

task alias add name email
Save a short name for an email. E.g. task alias add pedro pedro@gmail.com
task alias list
List all saved aliases.
task alias rm name
Remove an alias.

Your own username is an implicit alias — if you're logged in as alice@gmail.com, then task assign id alice resolves automatically.

Board

task -p project -m Kanban board with 3 columns (Pending, In Progress, On Hold). Running task with no arguments opens the board.
Kanban navigation
h/l column j/k task Enter open detail a add to column s start d done e edit r remove p filter project / search by title m toggle my tasks q quit
Detail view
j/k navigate fields Enter edit field r remove task Esc back to list
Field editing
Enter cycles status & priority Ctrl+S save description ←→↑↓ navigate calendar [/] prev/next month t today x clear date

Account

task login -e email
Login with email verification code. No passwords.
task logout
Logout and clear stored credentials.
task whoami
Show current user, plan, and trial status.
task version
Show installed CLI version.
task update
Update CLI to the latest version. Installs to user directory when possible (no sudo). The board also auto-updates silently in the background.
task upgrade
Upgrade to Pro plan. Opens checkout in your browser.
task cancel
Cancel your Pro subscription. Access continues until end of billing period.
task portal
Open the subscription management portal to update payment or billing.

Shell Completions

task completion bash|zsh|fish Generate shell completion scripts. Enables TAB completion for commands, task IDs, project aliases, member emails, and priorities.
task completion bash > ~/.local/share/bash-completion/completions/task
task completion zsh > ~/.zfunc/_task
task completion fish > ~/.config/fish/completions/task.fish

Web App

Access your tasks from any mobile browser at task.simples.media/app. The web app is a PWA (Progressive Web App) — install it on your phone for a native app experience.

Tasks List, add, edit, complete, and delete tasks. Filter by project, status, or tags. Pull-to-refresh for latest data.
Board Kanban board with 3 columns (Pending, In Progress, On Hold). Long-press and drag to move tasks between columns.
Projects Create projects, invite collaborators by email, and view team members.
Offline Works offline with cached data. Changes are queued and auto-synced when back online.
Install Tap "Add to Home Screen" in your browser menu for standalone mode without the browser bar.

AI Integration

Task CLI includes a native MCP server (Model Context Protocol) with 19 tools. AI agents can manage tasks, view attached screenshots, and download files — no plugins, no glue code.

Claude Code

claude mcp add task-manager -- task serve Register the MCP server. Auto-configured when you install Task CLI (if Claude Code is detected).

OpenAI Agents SDK

pip install openai-agents Install the OpenAI Agents SDK.
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(command="task", args=["serve"]) as server:
    agent = Agent(name="Task Manager", mcp_servers=[server])
    result = await Runner.run(agent, "list my tasks")
Save as openai_agent.py and run with python openai_agent.py.

Google Gemini

pip install google-genai mcp Install the Google Gen AI SDK with MCP support.
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai

server_params = StdioServerParameters(command="task", args=["serve"])
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        response = await client.aio.models.generate_content(
            model="gemini-2.5-flash", contents=prompt,
            config=genai.types.GenerateContentConfig(tools=[session]))
Save as gemini_agent.py and run with python gemini_agent.py.

Available MCP tools: list_tasks, add_task, start_task, complete_task, hold_task, show_task, edit_task, remove_task, list_projects, add_project, share_project, project_members, project_invites, set_profile, list_files, upload_file, download_file, get_file_url, delete_file. Any MCP-compatible client can use task serve via stdio.