Scripting

Tycana is built for scripts. Every write command returns structured output, every failure has a meaningful exit code, and quiet mode keeps your logs clean.

Output Formats

All commands support --format json and --format yaml for machine-readable output. The list command also supports --format csv.

# Read commands — returns arrays
tycana list --format json
tycana list --format json | jq '.[].Title'
tycana list --format yaml
tycana list --format csv                       # Spreadsheet-friendly

# Write commands — returns the created/modified/deleted task
tycana add "Deploy v2 @ops" --format json
tycana add "Deploy v2" -f json | jq -r .ID    # Extract just the ID
tycana done "auth bug" --format json           # Completed task with timestamp
tycana edit abc123 --due friday --format json   # Modified task
tycana rm abc123 --force --format json          # Deleted task (captured before removal)

# Bulk done — returns array of completed tasks
tycana done --project sprint-1 --format json

CSV Format

The list command supports --format csv for spreadsheet import and simple text processing.

# Export to a file
tycana list --format csv > tasks.csv

# Pipe to other tools
tycana list --format csv | column -t -s,

# Count tasks per project
tycana list --format csv | tail -n +2 | cut -d',' -f3 | sort | uniq -c | sort -rn

Columns: ID, Title, Project, Tags, Due, Completed, Estimate, Note. Tags are semicolon-separated within the field.

Quiet Mode

The global --quiet / -q flag suppresses all styled output. The command still runs — success or failure is communicated via exit code.

# Silent task creation
tycana add "background task" -q
echo $?                                        # 0 = success

# Quiet + format: format still outputs (quiet only suppresses styled text)
tycana add "deploy" -q --format json           # JSON output, no styled text

# Useful in scripts
tycana add "Daily standup" -q || echo "Failed to add task"

Exit Codes

Scripts can distinguish between different failure types:

Code	Meaning	Example
`0`	Success	Task created, completed, or found
`1`	General error	Config missing, storage error, invalid flags
`2`	Not found	`tycana done "nonexistent task"`
`3`	Ambiguous	`tycana done "bug"` matches multiple tasks

tycana done "deploy hotfix" -q
case $? in
  0) echo "Done" ;;
  2) echo "Task not found" ;;
  3) echo "Multiple matches — be more specific" ;;
  *) echo "Error" ;;
esac

Shell Completions

Tab completion for commands, flags, and filter names.

# Bash
tycana completion bash > ~/.bash_completion.d/tycana

# Zsh (Oh My Zsh)
tycana completion zsh > ~/.oh-my-zsh/completions/_tycana

# Fish
tycana completion fish > ~/.config/fish/completions/tycana.fish

Restart your shell or source the file to activate.

Scripting Recipes

Morning briefing

Add this to ~/.bashrc or ~/.zshrc. Every time you open a terminal, you see what’s on your plate.

# Show today's tasks on shell startup
if command -v tycana &>/dev/null; then
  tycana view today 2>/dev/null
fi

Overdue count in your prompt

A constant, ambient reminder. The count appears in red when you have overdue tasks, disappears when you’re caught up.

# Add to ~/.bashrc
_tycana_overdue() {
  local n
  n=$(tycana list --due overdue --format json 2>/dev/null | jq 'length')
  [[ "$n" -gt 0 ]] && echo " [$n overdue]"
}
PS1='\w$(_tycana_overdue)\$ '

Sprint kickoff from a template

Keep a sprint.txt in your project repo. Run it at the start of each sprint to create all the standard tasks.

# sprint.txt — one task per line, full natural language
Update dependencies @backend #sprint-12
Write migration scripts @backend #sprint-12
Update API docs @docs #sprint-12
QA smoke test @qa #sprint-12 due friday
Sprint retro friday 4pm @team #sprint-12

# Load the sprint
while IFS= read -r task; do
  tycana add "$task" -q && echo "  + $task"
done < sprint.txt

Git hook: auto-complete on merge

When you merge a branch, automatically complete the matching task. Add this as .git/hooks/post-merge:

#!/bin/bash
# .git/hooks/post-merge — mark task done when branch merges
BRANCH=$(git log -1 --pretty=%s | grep -oP '(#|task[- ]?)\K[a-z0-9]{6}')
if [ -n "$BRANCH" ]; then
  tycana done "$BRANCH" -q 2>/dev/null && \
    echo "tycana: completed task $BRANCH"
fi

Now commits like Merge: fix login timeout (#a1b2c3) auto-complete task a1b2c3.

Weekly review

How productive was your week? Run this before your Friday 1:1 or weekend wind-down.

#!/bin/bash
echo "=== Week of $(date +%B\ %d) ==="
echo ""

# What you got done
DONE=$(tycana list --completed --format json | jq '[.[] | select(.Completed)] | length')
echo "Completed: $DONE tasks"

# What's still overdue
OVERDUE=$(tycana list --due overdue --format json | jq 'length')
echo "Overdue:   $OVERDUE tasks"

# Breakdown by project
echo ""
echo "By project:"
tycana list --completed --format csv \
  | tail -n +2 | cut -d',' -f3 | sort | uniq -c | sort -rn \
  | while read count project; do
      echo "  $count  ${project:-"(none)"}"
    done

Your manager wants a status update. Your teammate needs the sprint backlog. CSV goes everywhere.

# Overdue tasks to clipboard (macOS)
tycana list --due overdue --format csv | pbcopy

# Overdue tasks to clipboard (Linux/Wayland)
tycana list --due overdue --format csv | wl-copy

# Email yourself this week's tasks
tycana list --due "this week" --format csv \
  | mail -s "Tasks this week" [email protected]

Calendar Export

`tycana export calendar`

Export tasks as an ICS file for one-time calendar import.

tycana export calendar
tycana export calendar --output ~/Desktop/tasks.ics
tycana export calendar --project backend --from today --to "in 2 weeks"

Shell Aliases

# Add to ~/.bashrc or ~/.zshrc
alias ta='tycana add'
alias tl='tycana list'
alias td='tycana done'
alias tt='tycana view today'
alias ts='tycana sync'