TeamDay CLI

The TeamDay CLI is a powerful command-line interface for managing agents, executing tasks, tracking work, and automating workflows directly from your terminal.

Table of Contents

• Installation
• Authentication
• Managing Agents
• Working with Spaces
• Task Management
• Execution Tracking
• Configuration
• Automation
• Command Reference

Installation

Prerequisites

• Node.js 18+ or Bun 1.0+
• A TeamDay account at teamday.ai

Install from Source (Currently)

cd /path/to/teamday/packages/cli
bun install
bun link

Verify installation:

teamday --version

Update CLI

cd /path/to/teamday/packages/cli
git pull
bun install

Authentication

OAuth Login (Recommended)

Interactive browser-based authentication with automatic token management:

teamday auth login

What happens:

1. CLI generates a secure authorization code
2. Opens your browser to TeamDay login page
3. You click "Authorize CLI"
4. CLI receives OAuth tokens automatically
5. Tokens saved securely in ~/.teamday/

First-time users: If you don't have an organization yet, one will be created automatically during CLI authorization.

Check Auth Status

teamday auth status

Output:

✓ Authenticated

Method: oauth
User ID: abc123xyz
Organization: org_456def
Expires: in 12 minutes

Refresh Token

OAuth tokens expire after 15 minutes. Refresh manually:

teamday auth refresh

Note: Refresh tokens last 90 days. After that, run teamday auth login again.

Logout

Clear stored credentials:

teamday auth logout

Personal Access Token (Alternative)

For automation and CI/CD, use PATs instead of OAuth:

teamday auth set-key "td_your_token_here"

Or use environment variable:

export TEAMDAY_API_TOKEN="td_your_token_here"

See API Keys Guide for creating PATs in the web app.

Managing Agents

List All Agents

teamday agents list

Output:

┌──────────────────────┬────────────────┬───────────────┬────────────────────┬────────────┐
│ id                   │ name           │ role          │ systemPrompt       │ visibility │
├──────────────────────┼────────────────┼───────────────┼────────────────────┼────────────┤
│ char_abc123          │ Joe            │ Assistant     │ You are helpful... │ private    │
│ char_def456          │ Code Reviewer  │ Developer     │ Review code for... │ private    │
└──────────────────────┴────────────────┴───────────────┴────────────────────┴────────────┘

Total: 2 agent(s)

Output formats:

# Table (default)
teamday agents list

# JSON for scripting
teamday agents list --format json

# YAML for readability
teamday agents list --format yaml

Get Agent Details

teamday agents get char_abc123

Shows complete agent configuration including:

• System prompt
• Model configuration
• Advanced tools enabled
• Creation/update timestamps
• Avatar and color settings

Create Agent

Basic creation:

teamday agents create \
  --name "My Assistant" \
  --role "Helper" \
  --system-prompt "You are a helpful AI assistant"

Advanced options:

teamday agents create \
  --name "Code Reviewer" \
  --role "Senior Developer" \
  --system-prompt "$(cat prompts/code-review.txt)" \
  --model "claude-3-5-sonnet-20241022" \
  --visibility private

Output:

✅ Agent created:
   ID: char_xyz789
   Name: Code Reviewer
   Status: active

Update Agent

teamday agents update char_abc123 \
  --name "Updated Name" \
  --role "New Role"

Update system prompt from file:

teamday agents update char_abc123 \
  --system-prompt "$(cat new-prompt.txt)"

Delete (Archive) Agent

teamday agents delete char_abc123

Output:

✅ Agent archived

   Note: Agent is archived, not permanently deleted

Archived agents:

• No longer appear in listings
• Cannot be executed
• Execution history is preserved
• Can be restored in the web app

Execute Agent

teamday agents exec char_abc123 "What is 2+2?"

With streaming (default):

teamday agents exec char_abc123 \
  "Review the authentication code" \
  --space s-project123 \
  --stream

Non-streaming:

teamday agents exec char_abc123 \
  "Quick question" \
  --no-stream

Options:

• --space <id> - Execute in workspace context
• --session <id> - Continue existing conversation
• --stream / --no-stream - Real-time vs batch
• --timeout <ms> - Max execution time (default: 300000)

Interactive Chat

Start a conversation with an agent:

teamday agents chat char_abc123

Features:

• Multi-turn conversations
• Streaming responses
• Session persistence
• Exit with Ctrl+C or type exit

Working with Spaces

Spaces are workspaces where agents can access files, git repositories, and collaborate on projects.

List Spaces

teamday spaces list

Output:

┌──────────────────────┬────────────────┬─────────────┬────────────┐
│ id                   │ name           │ visibility  │ members    │
├──────────────────────┼────────────────┼─────────────┼────────────┤
│ s-abc123             │ Backend API    │ private     │ user_xyz   │
│ s-def456             │ Marketing Site │ organization│ user_xyz   │
└──────────────────────┴────────────────┴─────────────┴────────────┘

Total: 2 space(s)

Create Space

Empty workspace:

teamday spaces create \
  --name "My Project" \
  --description "Backend API development" \
  --visibility private \
  --type empty

Visibility options:

• private - Only you can access
• organization - All org members can access
• public - Anyone with link can view

Output:

✅ Space created:
   ID: s-new123
   Name: My Project

Get Space Details

teamday spaces get s-abc123

Shows:

• Space metadata
• Gradient colors (for UI)
• Owner and members
• Creation/update timestamps

Delete Space

teamday spaces delete s-abc123

Note: Only space owners can delete. Space is archived (soft delete), not permanently removed.

Task Management

Tasks are work items that agents create to delegate work or track multi-step processes.

What Are Tasks?

Tasks in TeamDay are created by agents to:

• Delegate work to other agents
• Track multi-step processes
• Organize complex workflows
• Maintain accountability

Example: An agent building a feature might create tasks:

• "Review authentication code" → Assigned to Code Review Agent
• "Write unit tests" → Assigned to Test Agent
• "Update documentation" → Assigned to Docs Agent

List Tasks

teamday tasks list

Output:

┌────────────────────┬────────────────────┬─────────────┬──────────┐
│ id                 │ title              │ status      │ priority │
├────────────────────┼────────────────────┼─────────────┼──────────┤
│ task_123           │ Review PR #456     │ pending     │ high     │
│ task_124           │ Update docs        │ in_progress │ medium   │
└────────────────────┴────────────────────┴─────────────┴──────────┘

Total: 2 task(s)

Filter by status:

teamday tasks list --status pending
teamday tasks list --status in_progress
teamday tasks list --status completed

Filter by assignee:

teamday tasks list --assigned-to char_abc123

Filter by space:

teamday tasks list --space s-project123

Create Task

teamday tasks create \
  --title "Review Q4 Report" \
  --description "Analyze Q4 sales data and create summary" \
  --priority high

With assignment:

teamday tasks create \
  --title "Code Review" \
  --description "Review PR #123" \
  --assigned-to char_reviewer \
  --priority medium \
  --space s-codebase

Task properties:

• title - Required, short description
• description - Optional, detailed context
• priority - low|medium|high|urgent (default: medium)
• assignedTo - Agent ID to assign task to
• spaceId - Space context for the task

Output:

✅ Task created:
   ID: task_456
   Title: Review Q4 Report
   Status: pending

Get Task Details

teamday tasks get task_123

Shows full task information including creation date, completion date (if completed), and all metadata.

Update Task

teamday tasks update task_123 \
  --status in_progress \
  --assigned-to char_different

Status options:

• pending - Not started
• in_progress - Being worked on
• completed - Finished
• cancelled - Abandoned

Complete Task

Quick command to mark task as done:

teamday tasks complete task_123

Cancel Task

teamday tasks cancel task_123

Execution Tracking

Track agent executions, view history, and monitor running agents.

List Executions

teamday executions list

Output shows:

• Execution ID
• Agent ID
• Message/prompt
• Status (running, completed, failed, cancelled)
• Duration
• Timestamps

Filter by status:

teamday executions list --status running
teamday executions list --status completed

Get Execution Details

teamday executions get exec_abc123

Shows:

• Full execution metadata
• Chat/session IDs
• Delegation depth (for multi-agent workflows)
• Start and completion times

Cancel Execution

Stop a running agent:

teamday executions cancel exec_abc123

Configuration

View Configuration

# All settings
teamday config list

Output:

┌──────────────────────────────┬──────────────────────────┐
│ api_url                      │ http://localhost:3000    │
├──────────────────────────────┼──────────────────────────┤
│ format                       │ table                    │
├──────────────────────────────┼──────────────────────────┤
│ no_color                     │ false                    │
├──────────────────────────────┼──────────────────────────┤
│ timeout                      │ 300000                   │
├──────────────────────────────┼──────────────────────────┤
│ verbose                      │ false                    │
└──────────────────────────────┴──────────────────────────┘

Config file: /Users/you/.teamday/config.json

Get specific value:

teamday config get format

Update Settings

# Output format
teamday config set format json  # or: table, yaml

# API URL (for self-hosted)
teamday config set api_url https://your-instance.com

# Request timeout (milliseconds)
teamday config set timeout 600000  # 10 minutes

# Verbose output
teamday config set verbose true

Reset Settings

# Reset specific setting
teamday config unset format

# Reset all to defaults
teamday config reset

Environment Variables

Override config with environment variables:

export TEAMDAY_API_URL=http://localhost:3000
export TEAMDAY_API_TOKEN=td_your_token
export TEAMDAY_FORMAT=json
export TEAMDAY_NO_COLOR=1
export TEAMDAY_TIMEOUT=600000
export TEAMDAY_VERBOSE=true

Environment variables take precedence over config file settings.

Automation

Shell Scripts

Daily task summary:

#!/bin/bash
# daily-tasks.sh

echo "Tasks Summary - $(date +%Y-%m-%d)"
echo "================================"

echo -e "\n📋 Pending Tasks:"
teamday tasks list --status pending --format json | \
  jq -r '.[] | "\(.title) (Priority: \(.priority))"'

echo -e "\n✅ Completed Today:"
teamday tasks list --status completed --format json | \
  jq -r '.[] | "\(.title)"'

Make executable and run:

chmod +x daily-tasks.sh
./daily-tasks.sh

Scheduled with cron:

# Send daily email summary at 9 AM
0 9 * * * /path/to/daily-tasks.sh | mail -s "Daily Tasks" [email protected]

CI/CD Integration

GitHub Actions:

name: Agent Task Check

on: [push]

jobs:
  check-tasks:
    runs-on: ubuntu-latest
    steps:
      - name: Install TeamDay CLI
        run: |
          cd /tmp
          git clone https://github.com/yourorg/teamday.git
          cd teamday/packages/cli
          bun install
          bun link

      - name: Check pending tasks
        env:
          TEAMDAY_API_TOKEN: ${{ secrets.TEAMDAY_TOKEN }}
        run: |
          pending=$(teamday tasks list --status pending --format json | jq 'length')
          echo "Pending tasks: $pending"
          if [ $pending -gt 10 ]; then
            echo "⚠️  Warning: More than 10 pending tasks!"
          fi

Batch Operations

Create multiple tasks from CSV:

#!/bin/bash
# import-tasks.sh

while IFS=, read -r title description priority assignee; do
  teamday tasks create \
    --title "$title" \
    --description "$description" \
    --priority "$priority" \
    --assigned-to "$assignee"
done < tasks.csv

Export data for analysis:

#!/bin/bash
# export-execution-data.sh

# Get all executions as JSON
teamday executions list --format json > executions.json

# Analyze with jq
cat executions.json | jq '
  group_by(.status) |
  map({status: .[0].status, count: length})
'

Command Reference

Global Options

Available on all commands:

--help, -h         Show help
--version, -V      Show version
--format <format>  Output format (table|json|yaml)
--api-url <url>    Override API endpoint
--verbose          Show detailed output
--no-color         Disable colored output

auth

Authentication commands:

agents

Agent management:

List options:

• --status <active|archived>
• --visibility <private|organization|public>
• --tag <tag>
• --format <table|json|yaml>

Create options:

• --name <name> (required)
• --role <role>
• --system-prompt <prompt> (required)
• --model <model> (default: claude-3-5-sonnet-20241022)
• --visibility <private|organization|public> (default: private)

Exec options:

• --space <id> - Execute in workspace
• --session <id> - Continue session
• --stream / --no-stream - Streaming mode
• --timeout <ms> - Max execution time

spaces

Workspace management:

Create options:

• --name <name> (required)
• --description <desc>
• --visibility <private|organization|public> (default: private)
• --type <empty|git|starterKit> (default: empty)

tasks

Task management:

List options:

• --status <pending|in_progress|completed|cancelled>
• --assigned-to <agent-id>
• --space <space-id>
• --priority <low|medium|high|urgent>

Create options:

• --title <title> (required)
• --description <desc>
• --assigned-to <agent-id>
• --priority <low|medium|high|urgent> (default: medium)
• --space <space-id>

executions

Execution tracking:

List options:

• --status <pending|running|completed|failed|cancelled>
• --agent <agent-id>

config

Configuration management:

Available keys:

• api_url - API endpoint URL
• format - Output format (table|json|yaml)
• no_color - Disable colors (true|false)
• timeout - Request timeout in milliseconds
• verbose - Verbose output (true|false)

Tips & Tricks

JSON Output for Scripting

# Get agent ID programmatically
agent_id=$(teamday agents list --format json | jq -r '.[0].id')

# Count pending tasks
pending=$(teamday tasks list --status pending --format json | jq 'length')
echo "Pending tasks: $pending"

# Extract execution IDs
teamday executions list --format json | jq -r '.[].id' | \
  while read exec_id; do
    echo "Processing: $exec_id"
  done

Combining Commands

# Create task for each pending execution
teamday executions list --status running --format json | \
  jq -r '.[] | "\(.id),\(.message)"' | \
  while IFS=, read -r exec_id message; do
    teamday tasks create \
      --title "Review execution $exec_id" \
      --description "$message"
  done

Debugging

# Verbose output
teamday --verbose agents list

# See full config
teamday config list

# Check authentication
teamday auth status

# Test connection
teamday --api-url http://localhost:3000 agents list

Troubleshooting

Authentication Issues

Problem: 401 Unauthorized errors

Solutions:

# Check auth status
teamday auth status

# Refresh token
teamday auth refresh

# Re-authenticate
teamday auth logout
teamday auth login

Connection Errors

Problem: Cannot connect to API

Solutions:

# Check API URL
teamday config get api_url

# Update if needed
teamday config set api_url http://localhost:3000

# Test with explicit URL
teamday --api-url http://localhost:3000 agents list

Agent Execution Errors

Problem: 501 Server Error when executing agents

Possible causes:

• No Anthropic API key configured (user, org, or server level)
• Authentication tier selection issue

Solution: Ensure you have an API key configured:

# Check auth status
teamday auth status

# Option 1: Add API key in web app (Settings → Integrations)
# Option 2: Contact admin to configure server API key

Organization Not Found

Problem: organizationId: undefined on first login

Solution: The CLI automatically creates a personal organization during first OAuth login. If this fails, contact support.

Next Steps

• Learn more about agents: Understanding Agents
• Set up automation: See Automation section above
• API Reference: API Documentation
• Web Interface: Use the CLI alongside teamday.ai

Support

• Documentation: teamday.ai/docs
• Issues: GitHub Issues
• Community: Discord