AnyTask CLI Usage Guide

Comprehensive guide to using the AnyTask CLI for task management, workspace organization, and AI integration.

The anyt CLI is an AI-native task management tool built for Linear-style workflows. It supports both human users and AI agents as first-class citizens.

Installation
Quick Start
Global Options
Environment Management
Authentication
Workspace Management
Task Management
Dependency Management
Board & Visualization
AI Commands
MCP Integration
Configuration

Installation

The CLI is installed as part of the backend package:

# Install dependencies
make install

# Verify installation
anyt --version

Quick Start

# 1. Add an environment
anyt env add dev http://localhost:8000

# 2. Login with a token or agent key
anyt auth login --token                                    # Interactive prompt
# OR
anyt auth login --agent-key-value anyt_agent_...           # Direct agent key
# OR
export ANYT_AGENT_KEY=anyt_agent_... && anyt auth login   # Environment variable

# 3. Initialize a workspace
anyt init

# 4. View tasks on the board
anyt board

# 5. Create a task
anyt task add "Implement user authentication" --priority 1

# 6. Pick a task to work on
anyt task pick DEV-1

# 7. Show active task details
anyt active

# 8. Mark task as done
anyt task done

Global Options

anyt --version, -v    # Show version and exit
anyt --help          # Show help message

Health Check

anyt health

Check if the API server is reachable. Displays:

Current environment name
API URL
Server connectivity status

Example:

$ anyt health
Environment: dev
API URL: http://localhost:8000

✓ Server is healthy

Environment Management

Manage CLI environments (development, staging, production).

List Environments

anyt env list

Shows all configured environments with connectivity status. The current environment is marked with *.

Add Environment

anyt env add <name> <api-url> [--active]

Arguments:

name: Environment name (e.g., dev, staging, prod)
api-url: API base URL (must start with http:// or https://)

Options:

--active: Make this the active environment immediately

Examples:

anyt env add dev http://localhost:8000
anyt env add prod https://api.anytask.com --active

Switch Environment

anyt env switch <name>

Arguments:

name: Environment name to switch to

Examples:

anyt env switch prod

Show Current Environment

anyt env show

Displays:

Current environment name
API URL
Authentication status
Default workspace (if set)
Connection status

Note: Environment can be overridden with ANYT_ENV and ANYT_API_URL environment variables.

Authentication

Manage authentication credentials for accessing the AnyTask API.

anyt auth login [--env ENV] [--token] [--agent-key] [--token-value VALUE] [--agent-key-value VALUE]

Options:

--env, -e: Environment to login to (defaults to current)
--token: Use Personal Access Token (PAT) - prompts for value
--token-value: Personal Access Token value (skips prompt)
--agent-key: Use agent API key - prompts for value
--agent-key-value: Agent API key value (skips prompt)

Authentication Flows:

Personal Access Token (PAT):

# Interactive prompt
anyt auth login --token
# Enter: anyt_...

# Direct value
anyt auth login --token-value anyt_user_token_abc123

Agent API Key:

# Interactive prompt
anyt auth login --agent-key
# Enter: anyt_agent_...

# Direct value (recommended for scripts/automation)
anyt auth login --agent-key-value anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j

Environment Variable (Agent Key):

# Set environment variable
export ANYT_AGENT_KEY=anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j

# Login automatically uses ANYT_AGENT_KEY if set
anyt auth login

Device Code Flow (coming soon):

anyt auth login
# Interactive browser-based authentication (when ANYT_AGENT_KEY not set)

Logout

anyt auth logout [--env ENV] [--all]

Options:

--env, -e: Environment to logout from (defaults to current)
--all: Logout from all environments

Examples:

anyt auth logout              # Logout from current environment
anyt auth logout --env prod   # Logout from specific environment
anyt auth logout --all        # Logout from all environments

Who Am I

anyt auth whoami

Shows information about the currently authenticated user or agent:

Environment name and API URL
Authentication type (User Token or Agent Key)
Connection status
Accessible workspaces

Workspace Management

Manage workspaces - the top-level container for projects and tasks.

Initialize Workspace

anyt init [--create NAME] [--identifier ID] [--dir DIR]

Options:

--create: Create a new workspace with the given name
--identifier, -i: Workspace identifier (required when creating, e.g., "DEV")
--dir, -d: Directory to initialize (default: current directory)

Modes:

Link Existing/Auto-Create Workspace:

anyt init
# Uses or creates current workspace automatically

Create New Workspace:

anyt init --create "Development" --identifier DEV

Creates a .anyt/anyt.json workspace configuration file.

Note: The anyt init command replaces anyt workspace init as a top-level command for convenience.

List Workspaces

anyt workspace list

Shows all accessible workspaces with:

Name
Identifier
ID
Current workspace indicator (●)

Switch Workspace

anyt workspace switch [WORKSPACE_ID] [--dir DIR]

Arguments:

WORKSPACE_ID: Workspace ID or identifier to switch to (optional - shows picker if not provided)

Options:

--dir, -d: Directory to switch workspace in (default: current)

Examples:

anyt workspace switch DEV
anyt workspace switch 123
anyt workspace switch  # Interactive picker

Task Management

Create, view, edit, and manage tasks.

Create Task

anyt task add <title> [OPTIONS]

Arguments:

title: Task title (required)

Options:

-d, --description: Task description
-p, --priority: Priority (-2 to 2, default: 0)
- -2: Lowest
- -1: Low
- 0: Normal (default)
- 1: High
- 2: Highest
--labels: Comma-separated labels
--status: Task status (default: backlog)
- Values: backlog, todo, inprogress, done, canceled
--owner: Assign to user or agent ID
--estimate: Time estimate in hours
--project: Project ID (required for now)
--json: Output in JSON format

Examples:

anyt task add "Implement OAuth" --priority 1 --project 1
anyt task add "Fix login bug" -p 2 --labels bug,auth --project 1
anyt task add "Update docs" -d "Add API documentation" --estimate 3 --project 1

List Tasks

anyt task list [OPTIONS]

Options:

--status: Filter by status (comma-separated)
--mine: Show only tasks assigned to you
--labels: Filter by labels (comma-separated)
--sort: Sort field (priority, updated_at, created_at, status)
--order: Sort order (asc, desc)
--limit: Max number of tasks to show (default: 50)
--offset: Pagination offset (default: 0)
--json: Output in JSON format

Examples:

anyt task list
anyt task list --status inprogress,done
anyt task list --mine --sort priority
anyt task list --labels bug --limit 10

Show Task Details

anyt task show [IDENTIFIER] [--json]

Arguments:

IDENTIFIER: Task identifier (e.g., DEV-42) or ID (uses active task if not specified)

Options:

--json: Output in JSON format

Examples:

anyt task show DEV-42
anyt task show       # Uses active task
anyt task show 123   # By numeric ID

Fuzzy Matching:

DEV-42 → DEV-42 (exact)
dev42 → DEV-42 (case insensitive, no dash)
42 → 42 (just number)
DEV 42 → DEV-42 (with space)

Edit Task

anyt task edit [IDENTIFIER] [OPTIONS]

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Options:

--title: New title
-d, --description: New description
--status: New status
-p, --priority: New priority (-2 to 2)
--labels: Comma-separated labels (replaces all labels)
--owner: New owner ID
--estimate: New time estimate in hours
--ids: Multiple task IDs to edit (comma-separated, for bulk operations)
--if-match: Expected version for optimistic concurrency control
--dry-run: Preview changes without applying
--json: Output in JSON format

Examples:

# Edit single task
anyt task edit DEV-42 --status inprogress

# Bulk edit
anyt task edit --ids DEV-42,DEV-43,DEV-44 --status done

# Optimistic locking
anyt task edit DEV-42 --status done --if-match 5

# Preview changes
anyt task edit DEV-42 --priority 2 --dry-run

Mark Task as Done

anyt task done [IDENTIFIERS...] [--json]

Arguments:

IDENTIFIERS: Task identifier(s) (uses active task if not specified)

Options:

--json: Output in JSON format

Examples:

anyt task done DEV-42
anyt task done DEV-42 DEV-43 DEV-44
anyt task done  # Marks active task as done

If the active task is marked done, it's automatically cleared.

Delete Task

anyt task rm [IDENTIFIERS...] [--force] [--json]

Arguments:

IDENTIFIERS: Task identifier(s) (uses active task if not specified)

Options:

--force, -f: Skip confirmation prompt
--json: Output in JSON format

Examples:

anyt task rm DEV-42
anyt task rm DEV-42 DEV-43 --force
anyt task rm  # Deletes active task (with confirmation)

Performs soft delete (sets deleted_at timestamp).

Add Note to Task

anyt task note [IDENTIFIER] <note_text>

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)
note_text: Note content to add

Examples:

anyt task note DEV-42 "Implemented OAuth callback handler"
anyt task note "Fixed edge case with empty tokens"  # Uses active task

Adds a timestamped note to the task's description. The note is appended with a timestamp in the format:

---
[2025-10-18 14:30] Implemented OAuth callback handler

This is useful for tracking progress and adding context without formal commits.

Pick Active Task

anyt task pick [IDENTIFIER] [OPTIONS]

Arguments:

IDENTIFIER: Task identifier (shows interactive picker if not specified)

Options:

--status: Filter by status (comma-separated)
--project: Filter by project ID
--mine: Show only tasks assigned to you

Examples:

anyt task pick DEV-42
anyt task pick  # Interactive picker (coming soon)

Saves the task to .anyt/active_task.json for use as default in other commands.

Suggest Tasks

anyt task suggest [OPTIONS]

Get intelligent task recommendations based on priority, dependencies, and impact.

Options:

--limit INTEGER: Number of suggestions to return (default: 3)
--status TEXT: Filter by status, comma-separated (default: todo,backlog)
--json: Output in JSON format

Examples:

# Get top 3 recommended tasks
anyt task suggest

# Get top 5 suggestions
anyt task suggest --limit 5

# Filter for only TODO tasks
anyt task suggest --status todo

# Get JSON output for programmatic use
anyt task suggest --json

How it works:

The suggest command implements intelligent scoring based on:

Priority weighting (5x) - Higher priority tasks score better
Status bonus (+3 for todo, +1 for inprogress)
Dependencies (-10 penalty if blocked, +2 bonus if all deps complete)
Impact (+2 per task that this unblocks)

Tasks with incomplete dependencies are automatically filtered out.

Example output:

Top 3 Recommended Tasks:

1. DEV-42 - Implement OAuth callback [Priority: 2]
   Reason: Priority 2, No dependencies, Unblocks 2 tasks, Ready to work on
   Status: todo

2. DEV-45 - Add Redis caching [Priority: 1]
   Reason: Priority 1, No dependencies, Ready to work on
   Status: todo

3. DEV-48 - Update API documentation [Priority: 0]
   Reason: All dependencies complete, Ready to work on
   Status: backlog

Run: anyt task pick <ID> to start working on a task

Dependency Management

Manage task dependencies (prerequisite relationships).

Add Dependency

anyt task dep add [IDENTIFIER] --on <DEPENDENCIES>

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Options:

--on: Task(s) this depends on (comma-separated identifiers, required)

Examples:

# DEV-43 depends on DEV-42
anyt task dep add DEV-43 --on DEV-42

# DEV-50 depends on multiple tasks
anyt task dep add DEV-50 --on DEV-42,DEV-43,DEV-44

# Use active task
anyt task pick DEV-43
anyt task dep add --on DEV-42

Validation:

Prevents circular dependencies
Prevents self-dependencies
Shows warnings for already-existing dependencies

Remove Dependency

anyt task dep rm [IDENTIFIER] --on <DEPENDENCIES>

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Options:

--on: Task(s) to remove dependency on (comma-separated identifiers, required)

Examples:

anyt task dep rm DEV-43 --on DEV-42
anyt task dep rm DEV-50 --on DEV-42,DEV-43

List Dependencies

anyt task dep list [IDENTIFIER]

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Shows:

Dependencies (tasks this depends on) with status indicators
Blocks (tasks that depend on this) with status indicators

Status Indicators:

✓ done
⬤ inprogress
⬜ backlog

Example:

anyt task dep list DEV-43

Template Management

Manage reusable task templates stored as markdown files. Templates help standardize task creation with predefined structure.

Initialize Templates

anyt template init

Creates the template directory at ~/.config/anyt/templates/ and generates a default template with standard sections (Objectives, Acceptance Criteria, Technical Notes, etc.).

Example:

anyt template init
# Output: ✓ Template directory created
#         ✓ Default template created

List Templates

anyt template list

Shows all available templates (.md files in the template directory) with size and last modified date.

Example:

anyt template list
# Output: Available Templates table with Name, Size, Modified columns

Show Template

anyt template show [NAME]

Arguments:

NAME: Template name to display (default: "default")

Displays the template content rendered as markdown.

Examples:

anyt template show default
anyt template show feature-template

Edit Template

anyt template edit [NAME]

Arguments:

NAME: Template name to edit (default: "default")

Opens the template file in your system's default editor (respects $EDITOR environment variable).

Examples:

anyt template edit default
export EDITOR=vim && anyt template edit feature-template

Create Task from Template

anyt task create <title> [OPTIONS]

Arguments:

title: Task title (required)

Options:

--template, -t: Template name to use (default: "default")
--project: Project ID (required)
--priority, -p: Task priority (-2 to 2)
--owner: Assign to user or agent ID
--json: Output in JSON format

Examples:

anyt task create "Implement OAuth" --template feature-template --project 1 --priority 1
anyt task create "Fix login bug" -t bugfix --project 1 -p 2

The template content is loaded and used as the task's description, with placeholder variables replaced:

{datetime} → Current timestamp (e.g., "2025-10-18 14:30")

Template Location: ~/.config/anyt/templates/

Board & Visualization

Visualize tasks and workspace in different views.

Show Active Task

anyt active

Displays detailed information about the currently active task (set via anyt task pick).

Kanban Board

anyt board [OPTIONS]

Display tasks in a Kanban board view with columns:

Backlog
Active
Blocked (coming soon)
Done

Options:

--mine: Show only tasks assigned to you
--labels: Filter by labels (comma-separated)
--status: Filter by status (comma-separated)
--group-by: Group by (status, priority, owner, labels) - default: status
--sort: Sort within groups (priority, updated_at) - default: priority
--compact: Compact display mode
--limit: Max tasks per lane (default: 20)

Examples:

anyt board
anyt board --mine
anyt board --labels bug,auth
anyt board --compact
anyt board --group-by priority --sort updated_at

Timeline View

anyt timeline <identifier> [OPTIONS]

Show chronological timeline of task events, attempts, and artifacts.

Arguments:

identifier: Task identifier (e.g., DEV-42)

Options:

--events-only: Show only events
--attempts-only: Show only attempts
--since: Show events since date (YYYY-MM-DD)
--last: Show events from last N hours/days (e.g., 24h, 7d)
--show-artifacts: Include artifact previews
--compact: Compact format

Examples:

anyt timeline DEV-42
anyt timeline DEV-42 --last 24h
anyt timeline DEV-42 --events-only

Note: Full timeline API integration is pending.

Workspace Summary

anyt summary [OPTIONS]

Generate workspace summary with done, active, blocked, and next priorities.

Options:

--period: Summary period (today, weekly, monthly) - default: today
--format: Output format (text, markdown, json) - default: text

Examples:

anyt summary
anyt summary --period weekly
anyt summary --format markdown > summary.md

Shows:

✅ Done tasks (top 5)
🔄 Active tasks (with owners and update times)
🚫 Blocked tasks
📅 Next priorities (top 3 by priority)
Progress percentage

Dependency Graph

anyt graph [IDENTIFIER] [OPTIONS]

Visualize task dependencies as ASCII art or DOT format.

Arguments:

IDENTIFIER: Task identifier to show dependencies for (optional)

Options:

--full: Show all tasks in workspace
--format: Output format (ascii, dot) - default: ascii

Examples:

anyt graph DEV-42
anyt graph DEV-42 --format dot | dot -Tpng > graph.png
anyt graph --full

Shows:

Tasks this depends on (upstream)
Current task
Tasks that depend on this (downstream)

Status Indicators:

✓ done
• active
○ backlog

AI Commands

AI-powered task management features.

Decompose Goal

anyt ai decompose <goal> [OPTIONS]

Decompose a goal into actionable tasks using AI.

Arguments:

goal: Goal description or goal ID

Options:

--max-tasks: Maximum number of tasks to generate (default: 10)
--task-size: Preferred task size in hours (default: 4)
--dry-run: Preview tasks without creating them
--json: Output in JSON format

Examples:

anyt ai decompose "Add social login"
anyt ai decompose "Add social login" --dry-run
anyt ai decompose "Add social login" --max-tasks 10 --task-size 3

Note: API integration pending.

Organize Workspace

anyt ai organize [OPTIONS]

Organize workspace tasks using AI:

Normalize task titles to follow conventions
Suggest appropriate labels for tasks
Detect potential duplicate tasks

Options:

--dry-run: Preview changes without applying them
--auto: Apply all changes without confirmation
--titles-only: Only normalize task titles
--json: Output in JSON format

Examples:

anyt ai organize --dry-run
anyt ai organize --auto
anyt ai organize --titles-only

Note: API integration pending.

Fill Task Details

anyt ai fill <identifier> [OPTIONS]

Fill in missing details for a task using AI.

Arguments:

identifier: Task identifier (e.g., DEV-42)

Options:

--fields: Comma-separated fields to fill (description, acceptance, labels)
--json: Output in JSON format

Examples:

anyt ai fill DEV-42
anyt ai fill DEV-42 --fields description,acceptance
anyt ai fill DEV-42 --fields labels

Note: API integration pending.

Suggest Tasks

anyt ai suggest [--json]

Get AI suggestions for next task to work on based on:

Priority and dependencies
Unblocking downstream tasks
Quick wins and impact

Options:

--json: Output in JSON format

Example:

anyt ai suggest

Note: API integration pending.

Review Task

anyt ai review <identifier> [--json]

Get AI review of a task before marking done. Validates:

Title follows naming convention
Description is clear and complete
All acceptance criteria met
Dependencies satisfied
Tests exist and pass

Arguments:

identifier: Task identifier (e.g., DEV-42)

Options:

--json: Output in JSON format

Example:

anyt ai review DEV-42

Note: API integration pending.

Generate Summary

anyt ai summary [OPTIONS]

Generate workspace progress summary.

Options:

--period: Summary period (today, weekly, monthly) - default: today
--format: Output format (text, markdown, slack) - default: text

Examples:

anyt ai summary
anyt ai summary --period weekly
anyt ai summary --format markdown > summary.md

Note: API integration pending.

AI Configuration

anyt ai config [OPTIONS]

Manage AI provider settings.

Options:

--show: Show current AI configuration (default: true)
--model: Set AI model
--max-tokens: Set max tokens
--cache: Enable/disable cache (on/off)

Examples:

anyt ai config
anyt ai config --model claude-3-5-sonnet-20241022
anyt ai config --max-tokens 8192
anyt ai config --cache on

Default Configuration:

Provider: anthropic
Model: claude-3-5-sonnet-20241022
Max tokens: 4096
Temperature: 0.0
Cache enabled: true

Test AI Connection

anyt ai test

Test AI connection and settings. Validates:

API connectivity
Model availability
Prompt caching status

AI Usage Tracking

anyt ai usage [OPTIONS]

Track AI token usage and costs.

Options:

--workspace: Show workspace-level usage
--json: Output in JSON format

Examples:

anyt ai usage
anyt ai usage --workspace
anyt ai usage --json

Shows:

Operations breakdown (decompose, organize, fill, summary)
Total calls, tokens, and costs
Cache hit rate and savings

Note: Usage tracking implementation pending.

Upcoming CLI Features

The following features have fully implemented backend APIs but CLI commands are pending:

Label Management (Coming Soon)

Status: Backend API complete ✅ | CLI commands pending 🚧

The label management API is fully functional (/v1/workspaces/{workspace_id}/labels), allowing you to create, list, edit, and delete workspace labels. CLI commands will be added in a future release.

Planned Commands:

anyt label create <name> --color <hex> --description <text>
anyt label list
anyt label show <name>
anyt label edit <name> [OPTIONS]
anyt label rm <name>

Tracking: See task T7-32-CLI-Label-Management.md in .anyt/tasks/backlog/

Workaround: You can use the REST API directly:

# Create label
curl -X POST "http://localhost:8000/v1/workspaces/1/labels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 1, "name": "Bug", "color": "#FF0000"}'

# List labels
curl "http://localhost:8000/v1/workspaces/1/labels" \
  -H "Authorization: Bearer $TOKEN"

Task Views / Saved Filters (Coming Soon)

Status: Backend API complete ✅ | CLI commands pending 🚧

The task view API is fully functional (/v1/workspaces/{workspace_id}/task-views), allowing you to save commonly used task filters. CLI commands will be added in a future release.

Note: Task views are user-scoped and require user authentication (not available for agents).

Planned Commands:

anyt view create <name> --status <...> --priority-min <N> --labels <...>
anyt view list
anyt view show <name>
anyt view apply <name> (execute saved filter)
anyt view edit <name> [OPTIONS]
anyt view rm <name>
anyt view default <name> (set/clear default view)

Tracking: See task T7-33-CLI-TaskView-Management.md in .anyt/tasks/backlog/

Workaround: You can use the REST API directly:

# Create saved view
curl -X POST "http://localhost:8000/v1/workspaces/1/task-views" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": 1,
    "user_id": "user-123",
    "name": "High Priority",
    "filters": {"status": ["todo", "inprogress"], "priority_min": 1},
    "is_default": true
  }'

# List saved views
curl "http://localhost:8000/v1/workspaces/1/task-views" \
  -H "Authorization: Bearer $TOKEN"

MCP Integration

The AnyTask CLI provides Model Context Protocol (MCP) integration for Claude Code, allowing AI agents to interact with the task management system directly.

Start MCP Server

anyt mcp serve

Starts an MCP server for Claude Code integration. The server runs in the foreground and communicates via stdio.

Required Environment Variables:

ANYTASK_API_KEY: Agent API key for authentication
ANYTASK_API_URL: Backend URL (default: http://0.0.0.0:8000)
ANYTASK_WORKSPACE_ID: Workspace ID to operate in

Example:

export ANYTASK_API_KEY=anyt_agent_xxx
export ANYTASK_WORKSPACE_ID=1
anyt mcp serve

Show MCP Configuration

anyt mcp config

Displays the configuration snippet to add to Claude Code's MCP settings file (~/.config/claude/mcp.json).

Example Output:

{
  "mcpServers": {
    "anytask": {
      "command": "/path/to/anyt",
      "args": ["mcp", "serve"],
      "env": {
        "ANYTASK_API_URL": "http://0.0.0.0:8000",
        "ANYTASK_API_KEY": "YOUR_API_KEY_HERE",
        "ANYTASK_WORKSPACE_ID": "YOUR_WORKSPACE_ID"
      }
    }
  }
}

Setup Steps:

Replace YOUR_API_KEY_HERE with your agent API key
Replace YOUR_WORKSPACE_ID with your workspace ID
Get an agent key with: anyt auth agent-key create
Get your workspace ID with: anyt workspace list

Test MCP Connection

anyt mcp test

Tests the MCP server connection to verify:

API client initialization
Workspace access
Project access
Available tools (8 tools: list_tasks, select_task, create_task, update_task, start_attempt, finish_attempt, add_artifact, get_board)
Available resources (4 resource templates)

Example:

$ anyt mcp test
Testing MCP server connection...
✓ API client initialized
✓ Connected to workspace: DEV
✓ Connected to project: PROJ-1
✓ 8 tools available:
  - list_tasks
  - select_task
  - create_task
  - update_task
  - start_attempt
  - finish_attempt
  - add_artifact
  - get_board
✓ 4 resource templates available

✓ All tests passed!

Configuration

Configuration Files

The CLI stores configuration in:

Global config: ~/.config/anyt/config.json
- Environments
- Current environment
- Authentication tokens
Workspace config: .anyt/anyt.json
- Workspace ID
- Workspace name
- API URL
Active task: .anyt/active_task.json
- Current active task
- Pick timestamp

Environment Variables

Override configuration with environment variables:

ANYT_ENV: Override current environment
ANYT_API_URL: Override API URL
ANYT_AUTH_TOKEN: Override auth token
ANYT_AGENT_KEY: Agent API key (also used as default for anyt auth login)

Examples:

# Override environment
ANYT_ENV=prod anyt task list

# Override API URL
ANYT_API_URL=http://localhost:8000 anyt board

# Use agent key from environment (most common for CI/CD)
export ANYT_AGENT_KEY=anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j
anyt auth login  # Automatically uses ANYT_AGENT_KEY
anyt task list

# Override auth token
ANYT_AUTH_TOKEN=anyt_token_... anyt task list

JSON Output Mode

Most commands support --json flag for machine-readable output:

Success Response:

{
  "success": true,
  "data": { ... }
}

Error Response:

{
  "success": false,
  "error": "ErrorType",
  "message": "Error description",
  "suggestions": [ ... ]
}

Tips & Best Practices

Task Identifiers

The CLI supports flexible task identifier formats:

DEV-42 - Full identifier (workspace prefix + number)
dev42 - Case insensitive, no dash
42 - Just the number
DEV 42 - With space

All are automatically normalized.

Active Task Workflow

Pick a task to make it the default for subsequent commands:

anyt task pick DEV-42
anyt task show        # Shows DEV-42
anyt task edit --status inprogress
anyt task dep list
anyt task done        # Marks DEV-42 as done and clears active

Bulk Operations

Edit multiple tasks at once:

# Mark multiple tasks as done
anyt task done DEV-42 DEV-43 DEV-44

# Bulk edit status
anyt task edit --ids DEV-42,DEV-43,DEV-44 --status inprogress

# Delete multiple tasks
anyt task rm DEV-42 DEV-43 --force

Optimistic Locking

Prevent lost updates with version checking:

# Get current version
anyt task show DEV-42 --json | jq '.data.version'
# Output: 5

# Update with version check
anyt task edit DEV-42 --status done --if-match 5

If another user modifies the task in the meantime, the edit will fail with a version conflict error.

Dependency Management

Build complex task graphs:

# Create tasks
anyt task add "Setup database" --project 1 --priority 2
anyt task add "Create models" --project 1 --priority 1
anyt task add "Build API" --project 1 --priority 1

# Link dependencies
anyt task dep add DEV-2 --on DEV-1  # Models depend on database
anyt task dep add DEV-3 --on DEV-2  # API depends on models

# Visualize
anyt graph DEV-3

Board Filters

Focus on what matters:

# My high-priority bugs
anyt board --mine --labels bug --sort priority

# All in-progress tasks
anyt board --status inprogress

# Compact view for quick overview
anyt board --compact

Troubleshooting

Not authenticated

Error: Not authenticated

Solution: Login first

anyt auth login --token

Not in a workspace directory

Error: Not in a workspace directory

Solution: Initialize workspace

anyt workspace init

Task not found

Error: Task 'DEV-42' not found

Solution: Check task list

anyt task list
anyt task show DEV-42  # Shows suggestions for similar tasks

Connection failed

Error: Connection failed

Solution: Check environment configuration

anyt env show
anyt env list  # Verify API URL and connectivity

Examples

Complete Workflow Example

# 1. Setup
anyt env add dev http://localhost:8000
anyt auth login --token
anyt init

# 2. Verify connection
anyt health

# 3. Create tasks
anyt task add "Design authentication system" --project 1 --priority 2
anyt task add "Implement JWT tokens" --project 1 --priority 1
anyt task add "Add login endpoint" --project 1 --priority 1

# 4. Link dependencies
anyt task dep add DEV-2 --on DEV-1
anyt task dep add DEV-3 --on DEV-2

# 5. Work on tasks
anyt board
anyt task pick DEV-1
anyt task edit --status inprogress
anyt task done

# 6. Continue with next task
anyt task pick DEV-2
anyt task edit --status inprogress
anyt task done

# 7. View progress
anyt summary
anyt graph DEV-3

Agent Integration Example

# 1. Login as agent (multiple methods)

# Method A: Direct value (best for scripts/automation)
anyt auth login --agent-key-value anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j

# Method B: Environment variable (best for CI/CD)
export ANYT_AGENT_KEY=anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j
anyt auth login

# Method C: Interactive prompt
anyt auth login --agent-key
# Enter: anyt_agent_xxxxxxxxxxxxxxxxxxxxx

# 2. Initialize workspace
anyt init

# 3. Agent creates tasks
anyt task add "Automated test run" --owner agent-001 --project 1

# 4. Agent reports progress
anyt task edit DEV-42 --status inprogress
anyt task done DEV-42

# 5. Human reviews agent's work
anyt board --status done
anyt timeline DEV-42

Version

CLI Version: 0.1.0

For bug reports and feature requests, visit: https://github.com/supercarl87/AnyTaskBackend

AnyTask CLI Usage Guide

Comprehensive guide to using the AnyTask CLI for task management, workspace organization, and AI integration.

The anyt CLI is an AI-native task management tool built for Linear-style workflows. It supports both human users and AI agents as first-class citizens.

Installation
Quick Start
Global Options
Environment Management
Authentication
Workspace Management
Task Management
Dependency Management
Board & Visualization
AI Commands
MCP Integration
Configuration

Installation

The CLI is installed as part of the backend package:

# Install dependencies
make install

# Verify installation
anyt --version

Quick Start

# 1. Add an environment
anyt env add dev http://localhost:8000

# 2. Login with a token or agent key
anyt auth login --token                                    # Interactive prompt
# OR
anyt auth login --agent-key-value anyt_agent_...           # Direct agent key
# OR
export ANYT_AGENT_KEY=anyt_agent_... && anyt auth login   # Environment variable

# 3. Initialize a workspace
anyt init

# 4. View tasks on the board
anyt board

# 5. Create a task
anyt task add "Implement user authentication" --priority 1

# 6. Pick a task to work on
anyt task pick DEV-1

# 7. Show active task details
anyt active

# 8. Mark task as done
anyt task done

Global Options

anyt --version, -v    # Show version and exit
anyt --help          # Show help message

Health Check

anyt health

Check if the API server is reachable. Displays:

Current environment name
API URL
Server connectivity status

Example:

$ anyt health
Environment: dev
API URL: http://localhost:8000

✓ Server is healthy

Environment Management

Manage CLI environments (development, staging, production).

List Environments

anyt env list

Shows all configured environments with connectivity status. The current environment is marked with *.

Add Environment

anyt env add <name> <api-url> [--active]

Arguments:

name: Environment name (e.g., dev, staging, prod)
api-url: API base URL (must start with http:// or https://)

Options:

--active: Make this the active environment immediately

Examples:

anyt env add dev http://localhost:8000
anyt env add prod https://api.anytask.com --active

Switch Environment

anyt env switch <name>

Arguments:

name: Environment name to switch to

Examples:

anyt env switch prod

Show Current Environment

anyt env show

Displays:

Current environment name
API URL
Authentication status
Default workspace (if set)
Connection status

Note: Environment can be overridden with ANYT_ENV and ANYT_API_URL environment variables.

Authentication

Manage authentication credentials for accessing the AnyTask API.

anyt auth login [--env ENV] [--token] [--agent-key] [--token-value VALUE] [--agent-key-value VALUE]

Options:

--env, -e: Environment to login to (defaults to current)
--token: Use Personal Access Token (PAT) - prompts for value
--token-value: Personal Access Token value (skips prompt)
--agent-key: Use agent API key - prompts for value
--agent-key-value: Agent API key value (skips prompt)

Authentication Flows:

Personal Access Token (PAT):

# Interactive prompt
anyt auth login --token
# Enter: anyt_...

# Direct value
anyt auth login --token-value anyt_user_token_abc123

Agent API Key:

# Interactive prompt
anyt auth login --agent-key
# Enter: anyt_agent_...

# Direct value (recommended for scripts/automation)
anyt auth login --agent-key-value anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j

Environment Variable (Agent Key):

# Set environment variable
export ANYT_AGENT_KEY=anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j

# Login automatically uses ANYT_AGENT_KEY if set
anyt auth login

Device Code Flow (coming soon):

anyt auth login
# Interactive browser-based authentication (when ANYT_AGENT_KEY not set)

Logout

anyt auth logout [--env ENV] [--all]

Options:

--env, -e: Environment to logout from (defaults to current)
--all: Logout from all environments

Examples:

anyt auth logout              # Logout from current environment
anyt auth logout --env prod   # Logout from specific environment
anyt auth logout --all        # Logout from all environments

Who Am I

anyt auth whoami

Shows information about the currently authenticated user or agent:

Environment name and API URL
Authentication type (User Token or Agent Key)
Connection status
Accessible workspaces

Workspace Management

Manage workspaces - the top-level container for projects and tasks.

Initialize Workspace

anyt init [--create NAME] [--identifier ID] [--dir DIR]

Options:

--create: Create a new workspace with the given name
--identifier, -i: Workspace identifier (required when creating, e.g., "DEV")
--dir, -d: Directory to initialize (default: current directory)

Modes:

Link Existing/Auto-Create Workspace:

anyt init
# Uses or creates current workspace automatically

Create New Workspace:

anyt init --create "Development" --identifier DEV

Creates a .anyt/anyt.json workspace configuration file.

Note: The anyt init command replaces anyt workspace init as a top-level command for convenience.

List Workspaces

anyt workspace list

Shows all accessible workspaces with:

Name
Identifier
ID
Current workspace indicator (●)

Switch Workspace

anyt workspace switch [WORKSPACE_ID] [--dir DIR]

Arguments:

WORKSPACE_ID: Workspace ID or identifier to switch to (optional - shows picker if not provided)

Options:

--dir, -d: Directory to switch workspace in (default: current)

Examples:

anyt workspace switch DEV
anyt workspace switch 123
anyt workspace switch  # Interactive picker

Task Management

Create, view, edit, and manage tasks.

Create Task

anyt task add <title> [OPTIONS]

Arguments:

title: Task title (required)

Options:

-d, --description: Task description
-p, --priority: Priority (-2 to 2, default: 0)
- -2: Lowest
- -1: Low
- 0: Normal (default)
- 1: High
- 2: Highest
--labels: Comma-separated labels
--status: Task status (default: backlog)
- Values: backlog, todo, inprogress, done, canceled
--owner: Assign to user or agent ID
--estimate: Time estimate in hours
--project: Project ID (required for now)
--json: Output in JSON format

Examples:

anyt task add "Implement OAuth" --priority 1 --project 1
anyt task add "Fix login bug" -p 2 --labels bug,auth --project 1
anyt task add "Update docs" -d "Add API documentation" --estimate 3 --project 1

List Tasks

anyt task list [OPTIONS]

Options:

--status: Filter by status (comma-separated)
--mine: Show only tasks assigned to you
--labels: Filter by labels (comma-separated)
--sort: Sort field (priority, updated_at, created_at, status)
--order: Sort order (asc, desc)
--limit: Max number of tasks to show (default: 50)
--offset: Pagination offset (default: 0)
--json: Output in JSON format

Examples:

anyt task list
anyt task list --status inprogress,done
anyt task list --mine --sort priority
anyt task list --labels bug --limit 10

Show Task Details

anyt task show [IDENTIFIER] [--json]

Arguments:

IDENTIFIER: Task identifier (e.g., DEV-42) or ID (uses active task if not specified)

Options:

--json: Output in JSON format

Examples:

anyt task show DEV-42
anyt task show       # Uses active task
anyt task show 123   # By numeric ID

Fuzzy Matching:

DEV-42 → DEV-42 (exact)
dev42 → DEV-42 (case insensitive, no dash)
42 → 42 (just number)
DEV 42 → DEV-42 (with space)

Edit Task

anyt task edit [IDENTIFIER] [OPTIONS]

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Options:

--title: New title
-d, --description: New description
--status: New status
-p, --priority: New priority (-2 to 2)
--labels: Comma-separated labels (replaces all labels)
--owner: New owner ID
--estimate: New time estimate in hours
--ids: Multiple task IDs to edit (comma-separated, for bulk operations)
--if-match: Expected version for optimistic concurrency control
--dry-run: Preview changes without applying
--json: Output in JSON format

Examples:

# Edit single task
anyt task edit DEV-42 --status inprogress

# Bulk edit
anyt task edit --ids DEV-42,DEV-43,DEV-44 --status done

# Optimistic locking
anyt task edit DEV-42 --status done --if-match 5

# Preview changes
anyt task edit DEV-42 --priority 2 --dry-run

Mark Task as Done

anyt task done [IDENTIFIERS...] [--json]

Arguments:

IDENTIFIERS: Task identifier(s) (uses active task if not specified)

Options:

--json: Output in JSON format

Examples:

anyt task done DEV-42
anyt task done DEV-42 DEV-43 DEV-44
anyt task done  # Marks active task as done

If the active task is marked done, it's automatically cleared.

Delete Task

anyt task rm [IDENTIFIERS...] [--force] [--json]

Arguments:

IDENTIFIERS: Task identifier(s) (uses active task if not specified)

Options:

--force, -f: Skip confirmation prompt
--json: Output in JSON format

Examples:

anyt task rm DEV-42
anyt task rm DEV-42 DEV-43 --force
anyt task rm  # Deletes active task (with confirmation)

Performs soft delete (sets deleted_at timestamp).

Add Note to Task

anyt task note [IDENTIFIER] <note_text>

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)
note_text: Note content to add

Examples:

anyt task note DEV-42 "Implemented OAuth callback handler"
anyt task note "Fixed edge case with empty tokens"  # Uses active task

Adds a timestamped note to the task's description. The note is appended with a timestamp in the format:

---
[2025-10-18 14:30] Implemented OAuth callback handler

This is useful for tracking progress and adding context without formal commits.

Pick Active Task

anyt task pick [IDENTIFIER] [OPTIONS]

Arguments:

IDENTIFIER: Task identifier (shows interactive picker if not specified)

Options:

--status: Filter by status (comma-separated)
--project: Filter by project ID
--mine: Show only tasks assigned to you

Examples:

anyt task pick DEV-42
anyt task pick  # Interactive picker (coming soon)

Saves the task to .anyt/active_task.json for use as default in other commands.

Suggest Tasks

anyt task suggest [OPTIONS]

Get intelligent task recommendations based on priority, dependencies, and impact.

Options:

--limit INTEGER: Number of suggestions to return (default: 3)
--status TEXT: Filter by status, comma-separated (default: todo,backlog)
--json: Output in JSON format

Examples:

# Get top 3 recommended tasks
anyt task suggest

# Get top 5 suggestions
anyt task suggest --limit 5

# Filter for only TODO tasks
anyt task suggest --status todo

# Get JSON output for programmatic use
anyt task suggest --json

How it works:

The suggest command implements intelligent scoring based on:

Priority weighting (5x) - Higher priority tasks score better
Status bonus (+3 for todo, +1 for inprogress)
Dependencies (-10 penalty if blocked, +2 bonus if all deps complete)
Impact (+2 per task that this unblocks)

Tasks with incomplete dependencies are automatically filtered out.

Example output:

Top 3 Recommended Tasks:

1. DEV-42 - Implement OAuth callback [Priority: 2]
   Reason: Priority 2, No dependencies, Unblocks 2 tasks, Ready to work on
   Status: todo

2. DEV-45 - Add Redis caching [Priority: 1]
   Reason: Priority 1, No dependencies, Ready to work on
   Status: todo

3. DEV-48 - Update API documentation [Priority: 0]
   Reason: All dependencies complete, Ready to work on
   Status: backlog

Run: anyt task pick <ID> to start working on a task

Dependency Management

Manage task dependencies (prerequisite relationships).

Add Dependency

anyt task dep add [IDENTIFIER] --on <DEPENDENCIES>

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Options:

--on: Task(s) this depends on (comma-separated identifiers, required)

Examples:

# DEV-43 depends on DEV-42
anyt task dep add DEV-43 --on DEV-42

# DEV-50 depends on multiple tasks
anyt task dep add DEV-50 --on DEV-42,DEV-43,DEV-44

# Use active task
anyt task pick DEV-43
anyt task dep add --on DEV-42

Validation:

Prevents circular dependencies
Prevents self-dependencies
Shows warnings for already-existing dependencies

Remove Dependency

anyt task dep rm [IDENTIFIER] --on <DEPENDENCIES>

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Options:

--on: Task(s) to remove dependency on (comma-separated identifiers, required)

Examples:

anyt task dep rm DEV-43 --on DEV-42
anyt task dep rm DEV-50 --on DEV-42,DEV-43

List Dependencies

anyt task dep list [IDENTIFIER]

Arguments:

IDENTIFIER: Task identifier (uses active task if not specified)

Shows:

Dependencies (tasks this depends on) with status indicators
Blocks (tasks that depend on this) with status indicators

Status Indicators:

✓ done
⬤ inprogress
⬜ backlog

Example:

anyt task dep list DEV-43

Template Management

Manage reusable task templates stored as markdown files. Templates help standardize task creation with predefined structure.

Initialize Templates

anyt template init

Creates the template directory at ~/.config/anyt/templates/ and generates a default template with standard sections (Objectives, Acceptance Criteria, Technical Notes, etc.).

Example:

anyt template init
# Output: ✓ Template directory created
#         ✓ Default template created

List Templates

anyt template list

Shows all available templates (.md files in the template directory) with size and last modified date.

Example:

anyt template list
# Output: Available Templates table with Name, Size, Modified columns

Show Template

anyt template show [NAME]

Arguments:

NAME: Template name to display (default: "default")

Displays the template content rendered as markdown.

Examples:

anyt template show default
anyt template show feature-template

Edit Template

anyt template edit [NAME]

Arguments:

NAME: Template name to edit (default: "default")

Opens the template file in your system's default editor (respects $EDITOR environment variable).

Examples:

anyt template edit default
export EDITOR=vim && anyt template edit feature-template

Create Task from Template

anyt task create <title> [OPTIONS]

Arguments:

title: Task title (required)

Options:

--template, -t: Template name to use (default: "default")
--project: Project ID (required)
--priority, -p: Task priority (-2 to 2)
--owner: Assign to user or agent ID
--json: Output in JSON format

Examples:

anyt task create "Implement OAuth" --template feature-template --project 1 --priority 1
anyt task create "Fix login bug" -t bugfix --project 1 -p 2

The template content is loaded and used as the task's description, with placeholder variables replaced:

{datetime} → Current timestamp (e.g., "2025-10-18 14:30")

Template Location: ~/.config/anyt/templates/

Board & Visualization

Visualize tasks and workspace in different views.

Show Active Task

anyt active

Displays detailed information about the currently active task (set via anyt task pick).

Kanban Board

anyt board [OPTIONS]

Display tasks in a Kanban board view with columns:

Backlog
Active
Blocked (coming soon)
Done

Options:

--mine: Show only tasks assigned to you
--labels: Filter by labels (comma-separated)
--status: Filter by status (comma-separated)
--group-by: Group by (status, priority, owner, labels) - default: status
--sort: Sort within groups (priority, updated_at) - default: priority
--compact: Compact display mode
--limit: Max tasks per lane (default: 20)

Examples:

anyt board
anyt board --mine
anyt board --labels bug,auth
anyt board --compact
anyt board --group-by priority --sort updated_at

Timeline View

anyt timeline <identifier> [OPTIONS]

Show chronological timeline of task events, attempts, and artifacts.

Arguments:

identifier: Task identifier (e.g., DEV-42)

Options:

--events-only: Show only events
--attempts-only: Show only attempts
--since: Show events since date (YYYY-MM-DD)
--last: Show events from last N hours/days (e.g., 24h, 7d)
--show-artifacts: Include artifact previews
--compact: Compact format

Examples:

anyt timeline DEV-42
anyt timeline DEV-42 --last 24h
anyt timeline DEV-42 --events-only

Note: Full timeline API integration is pending.

Workspace Summary

anyt summary [OPTIONS]

Generate workspace summary with done, active, blocked, and next priorities.

Options:

--period: Summary period (today, weekly, monthly) - default: today
--format: Output format (text, markdown, json) - default: text

Examples:

anyt summary
anyt summary --period weekly
anyt summary --format markdown > summary.md

Shows:

✅ Done tasks (top 5)
🔄 Active tasks (with owners and update times)
🚫 Blocked tasks
📅 Next priorities (top 3 by priority)
Progress percentage

Dependency Graph

anyt graph [IDENTIFIER] [OPTIONS]

Visualize task dependencies as ASCII art or DOT format.

Arguments:

IDENTIFIER: Task identifier to show dependencies for (optional)

Options:

--full: Show all tasks in workspace
--format: Output format (ascii, dot) - default: ascii

Examples:

anyt graph DEV-42
anyt graph DEV-42 --format dot | dot -Tpng > graph.png
anyt graph --full

Shows:

Tasks this depends on (upstream)
Current task
Tasks that depend on this (downstream)

Status Indicators:

✓ done
• active
○ backlog

AI Commands

AI-powered task management features.

Decompose Goal

anyt ai decompose <goal> [OPTIONS]

Decompose a goal into actionable tasks using AI.

Arguments:

goal: Goal description or goal ID

Options:

--max-tasks: Maximum number of tasks to generate (default: 10)
--task-size: Preferred task size in hours (default: 4)
--dry-run: Preview tasks without creating them
--json: Output in JSON format

Examples:

anyt ai decompose "Add social login"
anyt ai decompose "Add social login" --dry-run
anyt ai decompose "Add social login" --max-tasks 10 --task-size 3

Note: API integration pending.

Organize Workspace

anyt ai organize [OPTIONS]

Organize workspace tasks using AI:

Normalize task titles to follow conventions
Suggest appropriate labels for tasks
Detect potential duplicate tasks

Options:

--dry-run: Preview changes without applying them
--auto: Apply all changes without confirmation
--titles-only: Only normalize task titles
--json: Output in JSON format

Examples:

anyt ai organize --dry-run
anyt ai organize --auto
anyt ai organize --titles-only

Note: API integration pending.

Fill Task Details

anyt ai fill <identifier> [OPTIONS]

Fill in missing details for a task using AI.

Arguments:

identifier: Task identifier (e.g., DEV-42)

Options:

--fields: Comma-separated fields to fill (description, acceptance, labels)
--json: Output in JSON format

Examples:

anyt ai fill DEV-42
anyt ai fill DEV-42 --fields description,acceptance
anyt ai fill DEV-42 --fields labels

Note: API integration pending.

Suggest Tasks

anyt ai suggest [--json]

Get AI suggestions for next task to work on based on:

Priority and dependencies
Unblocking downstream tasks
Quick wins and impact

Options:

--json: Output in JSON format

Example:

anyt ai suggest

Note: API integration pending.

Review Task

anyt ai review <identifier> [--json]

Get AI review of a task before marking done. Validates:

Title follows naming convention
Description is clear and complete
All acceptance criteria met
Dependencies satisfied
Tests exist and pass

Arguments:

identifier: Task identifier (e.g., DEV-42)

Options:

--json: Output in JSON format

Example:

anyt ai review DEV-42

Note: API integration pending.

Generate Summary

anyt ai summary [OPTIONS]

Generate workspace progress summary.

Options:

--period: Summary period (today, weekly, monthly) - default: today
--format: Output format (text, markdown, slack) - default: text

Examples:

anyt ai summary
anyt ai summary --period weekly
anyt ai summary --format markdown > summary.md

Note: API integration pending.

AI Configuration

anyt ai config [OPTIONS]

Manage AI provider settings.

Options:

--show: Show current AI configuration (default: true)
--model: Set AI model
--max-tokens: Set max tokens
--cache: Enable/disable cache (on/off)

Examples:

anyt ai config
anyt ai config --model claude-3-5-sonnet-20241022
anyt ai config --max-tokens 8192
anyt ai config --cache on

Default Configuration:

Provider: anthropic
Model: claude-3-5-sonnet-20241022
Max tokens: 4096
Temperature: 0.0
Cache enabled: true

Test AI Connection

anyt ai test

Test AI connection and settings. Validates:

API connectivity
Model availability
Prompt caching status

AI Usage Tracking

anyt ai usage [OPTIONS]

Track AI token usage and costs.

Options:

--workspace: Show workspace-level usage
--json: Output in JSON format

Examples:

anyt ai usage
anyt ai usage --workspace
anyt ai usage --json

Shows:

Operations breakdown (decompose, organize, fill, summary)
Total calls, tokens, and costs
Cache hit rate and savings

Note: Usage tracking implementation pending.

Upcoming CLI Features

The following features have fully implemented backend APIs but CLI commands are pending:

Label Management (Coming Soon)

Status: Backend API complete ✅ | CLI commands pending 🚧

The label management API is fully functional (/v1/workspaces/{workspace_id}/labels), allowing you to create, list, edit, and delete workspace labels. CLI commands will be added in a future release.

Planned Commands:

anyt label create <name> --color <hex> --description <text>
anyt label list
anyt label show <name>
anyt label edit <name> [OPTIONS]
anyt label rm <name>

Tracking: See task T7-32-CLI-Label-Management.md in .anyt/tasks/backlog/

Workaround: You can use the REST API directly:

# Create label
curl -X POST "http://localhost:8000/v1/workspaces/1/labels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 1, "name": "Bug", "color": "#FF0000"}'

# List labels
curl "http://localhost:8000/v1/workspaces/1/labels" \
  -H "Authorization: Bearer $TOKEN"

Task Views / Saved Filters (Coming Soon)

Status: Backend API complete ✅ | CLI commands pending 🚧

The task view API is fully functional (/v1/workspaces/{workspace_id}/task-views), allowing you to save commonly used task filters. CLI commands will be added in a future release.

Note: Task views are user-scoped and require user authentication (not available for agents).

Planned Commands:

anyt view create <name> --status <...> --priority-min <N> --labels <...>
anyt view list
anyt view show <name>
anyt view apply <name> (execute saved filter)
anyt view edit <name> [OPTIONS]
anyt view rm <name>
anyt view default <name> (set/clear default view)

Tracking: See task T7-33-CLI-TaskView-Management.md in .anyt/tasks/backlog/

Workaround: You can use the REST API directly:

# Create saved view
curl -X POST "http://localhost:8000/v1/workspaces/1/task-views" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": 1,
    "user_id": "user-123",
    "name": "High Priority",
    "filters": {"status": ["todo", "inprogress"], "priority_min": 1},
    "is_default": true
  }'

# List saved views
curl "http://localhost:8000/v1/workspaces/1/task-views" \
  -H "Authorization: Bearer $TOKEN"

MCP Integration

The AnyTask CLI provides Model Context Protocol (MCP) integration for Claude Code, allowing AI agents to interact with the task management system directly.

Start MCP Server

anyt mcp serve

Starts an MCP server for Claude Code integration. The server runs in the foreground and communicates via stdio.

Required Environment Variables:

ANYTASK_API_KEY: Agent API key for authentication
ANYTASK_API_URL: Backend URL (default: http://0.0.0.0:8000)
ANYTASK_WORKSPACE_ID: Workspace ID to operate in

Example:

export ANYTASK_API_KEY=anyt_agent_xxx
export ANYTASK_WORKSPACE_ID=1
anyt mcp serve

Show MCP Configuration

anyt mcp config

Displays the configuration snippet to add to Claude Code's MCP settings file (~/.config/claude/mcp.json).

Example Output:

{
  "mcpServers": {
    "anytask": {
      "command": "/path/to/anyt",
      "args": ["mcp", "serve"],
      "env": {
        "ANYTASK_API_URL": "http://0.0.0.0:8000",
        "ANYTASK_API_KEY": "YOUR_API_KEY_HERE",
        "ANYTASK_WORKSPACE_ID": "YOUR_WORKSPACE_ID"
      }
    }
  }
}

Setup Steps:

Replace YOUR_API_KEY_HERE with your agent API key
Replace YOUR_WORKSPACE_ID with your workspace ID
Get an agent key with: anyt auth agent-key create
Get your workspace ID with: anyt workspace list

Test MCP Connection

anyt mcp test

Tests the MCP server connection to verify:

API client initialization
Workspace access
Project access
Available tools (8 tools: list_tasks, select_task, create_task, update_task, start_attempt, finish_attempt, add_artifact, get_board)
Available resources (4 resource templates)

Example:

$ anyt mcp test
Testing MCP server connection...
✓ API client initialized
✓ Connected to workspace: DEV
✓ Connected to project: PROJ-1
✓ 8 tools available:
  - list_tasks
  - select_task
  - create_task
  - update_task
  - start_attempt
  - finish_attempt
  - add_artifact
  - get_board
✓ 4 resource templates available

✓ All tests passed!

Configuration

Configuration Files

The CLI stores configuration in:

Global config: ~/.config/anyt/config.json
- Environments
- Current environment
- Authentication tokens
Workspace config: .anyt/anyt.json
- Workspace ID
- Workspace name
- API URL
Active task: .anyt/active_task.json
- Current active task
- Pick timestamp

Environment Variables

Override configuration with environment variables:

ANYT_ENV: Override current environment
ANYT_API_URL: Override API URL
ANYT_AUTH_TOKEN: Override auth token
ANYT_AGENT_KEY: Agent API key (also used as default for anyt auth login)

Examples:

# Override environment
ANYT_ENV=prod anyt task list

# Override API URL
ANYT_API_URL=http://localhost:8000 anyt board

# Use agent key from environment (most common for CI/CD)
export ANYT_AGENT_KEY=anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j
anyt auth login  # Automatically uses ANYT_AGENT_KEY
anyt task list

# Override auth token
ANYT_AUTH_TOKEN=anyt_token_... anyt task list

JSON Output Mode

Most commands support --json flag for machine-readable output:

Success Response:

{
  "success": true,
  "data": { ... }
}

Error Response:

{
  "success": false,
  "error": "ErrorType",
  "message": "Error description",
  "suggestions": [ ... ]
}

Tips & Best Practices

Task Identifiers

The CLI supports flexible task identifier formats:

DEV-42 - Full identifier (workspace prefix + number)
dev42 - Case insensitive, no dash
42 - Just the number
DEV 42 - With space

All are automatically normalized.

Active Task Workflow

Pick a task to make it the default for subsequent commands:

anyt task pick DEV-42
anyt task show        # Shows DEV-42
anyt task edit --status inprogress
anyt task dep list
anyt task done        # Marks DEV-42 as done and clears active

Bulk Operations

Edit multiple tasks at once:

# Mark multiple tasks as done
anyt task done DEV-42 DEV-43 DEV-44

# Bulk edit status
anyt task edit --ids DEV-42,DEV-43,DEV-44 --status inprogress

# Delete multiple tasks
anyt task rm DEV-42 DEV-43 --force

Optimistic Locking

Prevent lost updates with version checking:

# Get current version
anyt task show DEV-42 --json | jq '.data.version'
# Output: 5

# Update with version check
anyt task edit DEV-42 --status done --if-match 5

If another user modifies the task in the meantime, the edit will fail with a version conflict error.

Dependency Management

Build complex task graphs:

# Create tasks
anyt task add "Setup database" --project 1 --priority 2
anyt task add "Create models" --project 1 --priority 1
anyt task add "Build API" --project 1 --priority 1

# Link dependencies
anyt task dep add DEV-2 --on DEV-1  # Models depend on database
anyt task dep add DEV-3 --on DEV-2  # API depends on models

# Visualize
anyt graph DEV-3

Board Filters

Focus on what matters:

# My high-priority bugs
anyt board --mine --labels bug --sort priority

# All in-progress tasks
anyt board --status inprogress

# Compact view for quick overview
anyt board --compact

Troubleshooting

Not authenticated

Error: Not authenticated

Solution: Login first

anyt auth login --token

Not in a workspace directory

Error: Not in a workspace directory

Solution: Initialize workspace

anyt workspace init

Task not found

Error: Task 'DEV-42' not found

Solution: Check task list

anyt task list
anyt task show DEV-42  # Shows suggestions for similar tasks

Connection failed

Error: Connection failed

Solution: Check environment configuration

anyt env show
anyt env list  # Verify API URL and connectivity

Examples

Complete Workflow Example

# 1. Setup
anyt env add dev http://localhost:8000
anyt auth login --token
anyt init

# 2. Verify connection
anyt health

# 3. Create tasks
anyt task add "Design authentication system" --project 1 --priority 2
anyt task add "Implement JWT tokens" --project 1 --priority 1
anyt task add "Add login endpoint" --project 1 --priority 1

# 4. Link dependencies
anyt task dep add DEV-2 --on DEV-1
anyt task dep add DEV-3 --on DEV-2

# 5. Work on tasks
anyt board
anyt task pick DEV-1
anyt task edit --status inprogress
anyt task done

# 6. Continue with next task
anyt task pick DEV-2
anyt task edit --status inprogress
anyt task done

# 7. View progress
anyt summary
anyt graph DEV-3

Agent Integration Example

# 1. Login as agent (multiple methods)

# Method A: Direct value (best for scripts/automation)
anyt auth login --agent-key-value anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j

# Method B: Environment variable (best for CI/CD)
export ANYT_AGENT_KEY=anyt_agent_O1HFI42vTa442u6XSCAZISxLVoW8Xd7j
anyt auth login

# Method C: Interactive prompt
anyt auth login --agent-key
# Enter: anyt_agent_xxxxxxxxxxxxxxxxxxxxx

# 2. Initialize workspace
anyt init

# 3. Agent creates tasks
anyt task add "Automated test run" --owner agent-001 --project 1

# 4. Agent reports progress
anyt task edit DEV-42 --status inprogress
anyt task done DEV-42

# 5. Human reviews agent's work
anyt board --status done
anyt timeline DEV-42

Version

CLI Version: 0.1.0

For bug reports and feature requests, visit: https://github.com/supercarl87/AnyTaskBackend

AnyTask CLI Usage Guide

Comprehensive guide to using the AnyTask CLI for task management, workspace organization, and AI integration.

Table of Contents

Installation

Quick Start

Global Options

Health Check

Environment Management

List Environments

Add Environment

Switch Environment

Show Current Environment

Authentication

Login

Logout

Who Am I

Workspace Management

Initialize Workspace

List Workspaces

Switch Workspace

Task Management

Create Task

List Tasks

Show Task Details

Edit Task

Mark Task as Done

Delete Task

Add Note to Task

Pick Active Task

Suggest Tasks

Dependency Management

Add Dependency

Remove Dependency

List Dependencies

Template Management

Initialize Templates

List Templates

Show Template

Edit Template

Create Task from Template

Board & Visualization

Show Active Task

Kanban Board

Timeline View

Workspace Summary

Dependency Graph

AI Commands

Decompose Goal

Organize Workspace

Fill Task Details

Suggest Tasks

Review Task

Generate Summary

AI Configuration

Test AI Connection

AI Usage Tracking

Upcoming CLI Features

Label Management (Coming Soon)

Task Views / Saved Filters (Coming Soon)

MCP Integration

Start MCP Server

Show MCP Configuration

Test MCP Connection

Configuration

Configuration Files

Environment Variables

JSON Output Mode

Tips & Best Practices

Task Identifiers

Active Task Workflow

Bulk Operations

Optimistic Locking

Dependency Management

Board Filters

Troubleshooting

Not authenticated

Not in a workspace directory

Task not found

Connection failed

Examples