Tycana Documentation

Complete guide to mastering Tycana CLI for professional task management.

Quick Start

Get productive with Tycana in 5 minutes.

1. Verify Installation

tycana version
# Should show the current installed version

2. Create Your First Task

# Simple task
tycana add "Review pull request"

# With natural language parsing
tycana add "Call client tomorrow at 2pm @work #urgent ~30m"

3. View and Complete Tasks

# See your tasks
tycana list

# Mark task complete
tycana done <task-id>

# See today's work
tycana today

4. Enable Premium Features (Beta)

# Login for cloud sync
tycana account login
# or: tycana login (legacy)

# Check account status
tycana account
tycana account status

You’re ready! Your tasks are now managed locally with optional cloud sync across devices.

Essential Commands

Core commands for daily task management.

Task Management

tycana add

Create tasks with natural language parsing:

# Basic task
tycana add "Fix authentication bug"

# Full natural language
tycana add "Review PR #234 by friday @backend #code-review ~45m"

# Interactive form
tycana add

Natural Language Support:

  • Projects: @project or for project
  • Tags: #tag #urgent #bug
  • Due dates: by friday, tomorrow, in 3 days
  • Time estimates: ~2h, est:30m, about 1 hour
  • Date ranges: next 3 days, past week, until friday

tycana list

View tasks with filtering and natural language queries:

# All tasks
tycana list

# Natural language queries (NEW!)
tycana list "next 3 days"              # Tasks due in next 3 days
tycana list "past week"                 # Tasks from past 7 days
tycana list "until friday"              # Tasks due through Friday
tycana list "@work #urgent past 3 days" # Complex combined queries

# Traditional flag filtering
tycana list --project backend
tycana list --due today
tycana list --due "this week"
tycana list --due overdue
tycana list --tags urgent
tycana list --completed

tycana done

Complete tasks with natural selection:

# Interactive selection
tycana done

# Natural task selection by title (NEW!)
tycana done "marketing meeting"        # Finds by title
tycana done "review pull request"      # Fuzzy matching

# Complete by ID (traditional)
tycana done abc123

# Toggle completion (undo if needed)
tycana done abc123  # Mark complete
tycana done abc123  # Mark incomplete

tycana today

View today’s work:

# Tasks due or scheduled today
tycana today

# Timeline view with schedule
tycana today --timeline

Organization

Projects

Every task belongs to a project:

# Explicit project
tycana add "Design logo @marketing"

# Auto-detected from current directory/git repo
tycana add "Fix bug"  # Uses current project context

# View by project
tycana list --project marketing

Tags

Flexible categorization:

# Add multiple tags
tycana add "Security audit #security #urgent #compliance"

# Filter by tags
tycana list --tags security
tycana list --tags "urgent,critical"  # OR logic

Saved Filters

Create reusable filter combinations:

# Save complex filter
tycana filter save work-urgent \
  --project work \
  --tags urgent \
  --due "this week"

# Apply instantly
tycana filter work-urgent

# List saved filters
tycana filter list

Time Management

Scheduling

Assign specific times to tasks:

# Schedule task for specific time
tycana schedule 1 "tomorrow 2pm"

# With duration and location
tycana schedule 1 "friday 10am" --duration 2h --location "Office"

# List scheduled tasks
tycana schedule --list

# Clear schedule
tycana schedule 1 --clear

Time Tracking

Track work time:

# Start tracking
tycana start abc123

# Check status
tycana active

# Pause/resume
tycana pause
tycana resume

# Stop tracking
tycana stop

Configuration

# View and modify settings
tycana config
tycana config get telemetry.enabled
tycana config set git.remote upstream

# Open config file in editor
tycana config edit

Advanced Natural Language Features

Tycana’s unified natural language parser brings powerful query capabilities to all commands.

Date Range Queries

Query tasks using natural time expressions:

# Relative day ranges (1-14 days)
tycana list "next 3 days"              # Tasks due in next 3 days
tycana list "past 5 days"              # Tasks from past 5 days
tycana list "last week"                 # Previous week (Mon-Sun)

# Until/through patterns
tycana list "until friday"             # Today through Friday
tycana list "through next week"        # Today through end of next week

# Combined with other filters
tycana list "@work next 5 days"        # Work tasks due in next 5 days
tycana list "#urgent past 3 days"      # Urgent tasks from past 3 days
tycana list "backend tasks until tuesday" # Backend tasks through Tuesday

Natural Task Selection

Find and manage tasks by title across all commands:

# Complete tasks by title
tycana done "marketing meeting"
tycana done "code review"

# Edit tasks by title  
tycana edit "documentation task"

# Remove tasks by title
tycana rm "old planning task"

# Schedule tasks by title
tycana schedule "team standup" "tomorrow 9am"

Unified Command Experience

All commands support consistent natural language patterns:

Human-Friendly:

tycana add "Fix bug @api #urgent ~2h"
tycana done "marketing meeting"
tycana list "@work #urgent next 3 days"

Automation-Friendly:

tycana add "Fix bug" --project api --tags urgent --estimate 2h
tycana done abc123 --note "Completed successfully"
tycana list --project work --tags urgent --due "next 3 days"

Configuration Management

Control your Tycana settings and recurring task templates.

tycana config

Manage configuration settings via command line:

# View current configuration
tycana config
tycana config get

# Get specific values
tycana config get telemetry.enabled
tycana config get recurring.cleanup.enabled
tycana config get git.remote

# Set configuration values
tycana config set telemetry.enabled true
tycana config set git.remote upstream
tycana config set recurring.cleanup.daily_threshold_days 5

# Open config file in editor
tycana config edit

# Reset to defaults (with backup)
tycana config reset

# Show config file location
tycana config path

Key Configuration Sections:

  • Git Settings: Remote repository and auto-sync preferences
  • Authentication: Pro account credentials (automatically managed)
  • Sync Settings: Server URL and device management
  • Telemetry: Usage analytics preferences
  • Recurring Tasks: Cleanup thresholds and automation settings

Pro Features in Config:

# Recurring task cleanup settings (Pro only)
tycana config get recurring.cleanup.enabled                  # Default: true
tycana config get recurring.cleanup.daily_threshold_days     # Default: 3
tycana config get recurring.cleanup.weekly_threshold_days    # Default: 14
tycana config get recurring.cleanup.monthly_threshold_days   # Default: 60

# Adjust cleanup behavior
tycana config set recurring.cleanup.daily_threshold_days 7   # Keep daily tasks longer
tycana config set recurring.cleanup.enabled false           # Disable auto-cleanup

tycana recur (Pro Feature)

Manage recurring task templates:

# List all recurring templates
tycana recur list
# Shows patterns like:
#   ↻ abc123    Daily standup              Pattern: Weekdays (Mon-Fri)
#   ↻ def456    Team meeting               Pattern: Weekly on Mon

# Delete recurring template (with confirmation)
tycana recur delete "Daily standup"
tycana recur delete abc123

# Show template details
tycana recur show abc123

Creating Recurring Tasks: Recurring tasks are created through natural language in tycana add:

# Daily patterns
tycana add "Check email daily"
tycana add "Daily backup at midnight"

# Weekday patterns (Monday-Friday)  
tycana add "Daily standup every weekday at 9am"
tycana add "End of day review weekdays"

# Weekly patterns
tycana add "Team meeting every monday 2pm"
tycana add "Client call every friday 10am"

# Monthly patterns
tycana add "Pay rent monthly on the 1st"
tycana add "Board meeting monthly on the 15th"

Template Lifecycle:

  • Instance Generation: Automatically creates task instances from templates
  • Rolling Window: Shows current + next 2-3 instances (not overwhelming)
  • Smart Cleanup: Old missed instances cleaned automatically based on pattern frequency
  • Calendar Integration: Recurring instances appear in calendar subscriptions

Template vs Instance Editing:

  • Edit template → affects all future instances
  • Edit instance → affects only that specific occurrence
  • Delete template → removes template and all future instances
  • Delete instance → removes only that occurrence

Premium Features

Beta features available with cloud sync account.

Cloud Sync Setup

Login and Device Registration

# Authenticate with premium account
tycana account login
# Email: [email protected]
# Password: ********
# Logged in successfully as [email protected]
# Device registered: your-laptop-20250607

# Check account status
tycana account
# Shows: Tycana Pro, Device: your-laptop-20250607

# Other account management
tycana account logout    # Sign out
tycana account upgrade   # Upgrade to Pro

Multi-Device Sync

# Manual sync
tycana sync

# Automatic sync happens on:
# - Task creation: tycana add
# - Task completion: tycana done
# - Task editing: tycana edit
# - Task removal: tycana rm

Multi-Device Workflow:

  1. Add tasks on laptop → automatically syncs
  2. View tasks on desktop → same tasks appear
  3. Complete work on desktop → syncs back
  4. Check laptop → completion status updated

Calendar Integration

Live Calendar Subscriptions

# Create subscription feed
tycana calendar subscribe
# Calendar subscription created!
# Add this URL to any calendar app:
# https://app.tycana.com/calendar/feed/your-secure-token.ics

Setup Instructions:

  • iOS: Settings → Calendar → Add Subscription → Paste URL
  • Google: Other calendars → Subscribe to calendar → Paste URL
  • Outlook: Add calendar → From internet → Paste URL
  • Apple Calendar: File → New Calendar Subscription → Paste URL

Manual Calendar Export

# Export all scheduled tasks
tycana export calendar

# Save to file
tycana export calendar --output schedule.ics

# Filter by date range
tycana export calendar --from today --to "next week"

# Filter by project
tycana export calendar --project work

Calendar Features:

  • Updates automatically every 15 minutes
  • Compatible with all major calendar apps
  • Shows scheduled tasks alongside meetings
  • Includes task metadata (project, tags, due dates)

Web Dashboard

Access your account through the web interface:

  • Device Management: View and remove registered devices
  • Account Settings: Update email and password
  • Usage Overview: Track productivity across devices
  • Task Summary: Basic task viewing (CLI remains primary interface)

Advanced Workflows

Power user patterns and automation.

Daily Planning

# Morning routine
tycana today                    # See today's work
tycana list --due overdue       # Handle urgent items
tycana plan                     # AI-optimized daily plan

# Schedule important work
tycana schedule 1 "10am" --duration 2h
tycana schedule 3 "2pm" --duration 45m

# View your day
tycana today --timeline

Project Management

# Project-specific filters
tycana filter save backend-urgent \
  --project backend \
  --tags "urgent,critical" \
  --due "this week"

# Sprint planning
tycana list --project backend --due "next week"

# Weekly review
tycana list --completed --due "this week" --project backend

Automation and Scripting

Output Formats

# JSON for scripts
tycana list --format json
tycana list --due today --format json | jq -r '.[].Title'

# YAML for configuration
tycana list --format yaml

# CSV export (using jq)
tycana list --format json | jq -r '.[] | [.ID, .Title, .Project] | @csv'

Shell Integration

# Useful aliases
alias ta='tycana add'
alias tt='tycana today'
alias td='tycana done'
alias tl='tycana list'

# Daily standup report
echo "=== Completed Yesterday ==="
tycana list --completed --due yesterday
echo -e "\n=== Today's Plan ==="
tycana today

Beta Feedback

Help us improve Tycana.

Reporting Issues

Bug Reports:

  1. Include command that failed
  2. Provide exact error message
  3. Mention your operating system
  4. Email: [email protected]

Feature Requests:

  1. Describe your workflow challenge
  2. Explain your ideal solution
  3. Include specific use cases
  4. Email: [email protected]

Beta Testing Best Practices

Effective Testing:

  • Use Tycana for real daily work
  • Try edge cases with natural language parsing
  • Test sync across multiple devices
  • Experiment with calendar integration

Helpful Feedback:

  • Specific examples of what worked/didn’t work
  • Comparison to your previous workflow
  • Suggestions for improvement
  • Screenshots for visual issues

Troubleshooting

Common issues and solutions.

Sync Issues

Login Problems:

# Check if logged in
tycana account

# Re-authenticate if needed
tycana account logout
tycana account login

Sync Not Working:

# Manual sync
tycana sync

# Check for connection issues
# Sync requires internet connection
# Tasks are queued locally if offline

# Check device registration
tycana account  # Should show device name

Calendar Integration

Subscription Not Working:

  1. Verify URL was copied completely
  2. Check calendar app supports ICS subscriptions
  3. Wait up to 15 minutes for first sync
  4. Try manual export: tycana export calendar

Tasks Not Appearing:

# Verify tasks are scheduled
tycana schedule --list

# Check date range
tycana export calendar --from today --to "next week"

# Only scheduled tasks appear in calendar
# Use: tycana schedule <task> <time>

Performance Issues

Slow Response:

# Check task count
tycana list --format json | jq length

# Large task lists (1000+) may be slower
# Consider archiving completed tasks

High Memory Usage:

  • Restart CLI: exit and re-run commands
  • Contact support for persistent issues

Getting Help

Self-Service:

  1. Check this documentation
  2. Try tycana help <command>
  3. Review error messages carefully

Direct Support:

  • Email: [email protected]
  • Response Time: Within 24 hours for beta testers
  • Include: Command output, error messages, OS details

Advanced Reference

Complete Command List

Core Commands

  • tycana add - Create tasks
  • tycana list - View tasks
  • tycana done - Complete tasks
  • tycana edit - Modify tasks
  • tycana rm - Remove tasks
  • tycana today - Today’s tasks
  • tycana inbox - Uncategorized tasks

Time Management

  • tycana schedule - Assign times to tasks
  • tycana start/stop/pause/resume - Time tracking
  • tycana active - Current tracking status

Organization

  • tycana filter - Saved filter management
  • tycana plan - AI daily planning
  • tycana insights - Productivity analytics

Sync & Export

  • tycana account - Account management (login/logout/status/upgrade)
  • tycana sync - Manual synchronization
  • tycana export - Calendar and data export

Configuration & Settings

  • tycana config - Manage configuration settings
  • tycana recur - Manage recurring task templates (Pro)

Utility

  • tycana undo - Reverse last action
  • tycana version - Check for updates
  • tycana help - Command help

Data Storage

Local Files:

  • Location: ~/.tycana/tasks/
  • Format: Monthly YAML files (2025-06.yaml)
  • Human-readable and directly editable
  • Git-friendly for version control

Cloud Sync:

  • Encrypted in transit (HTTPS)
  • Per-user data isolation
  • UTC storage with local timezone display
  • Last-write-wins conflict resolution

For comprehensive details, see the complete user guide

Questions? Email [email protected]