TeamDay CLI

The TeamDay CLI is a command-line interface for managing your AI team — characters, agents, spaces, skills, MCPs, secrets, and more — directly from the terminal.

Installation

Prerequisites

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

Install via Bun

# Clone the repository
git clone https://github.com/TeamDay-AI/teamday.git
cd teamday/packages/cli

# Install dependencies
bun install

# Link globally so you can run `teamday` from anywhere
bun link

Verify installation:

teamday --version

Update

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

Connecting to TeamDay

The CLI connects to a TeamDay API endpoint. TeamDay is available in multiple regions:

Set your endpoint

# Set via CLI config
teamday config set api_url https://us.teamday.ai

# Or via environment variable (takes precedence)
export TEAMDAY_API_URL=https://us.teamday.ai

# Or pass per-command
teamday --api-url https://us.teamday.ai spaces list

Authentication

OAuth Login (Recommended)

Interactive browser-based login with automatic token management:

teamday auth login

What happens:

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

First-time users get an organization created automatically.

Check Status

teamday auth status

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

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

Personal Access Token (for CI/CD)

For automation and scripts, use PATs instead of OAuth:

# Set directly
teamday auth set-key "td_your_token_here"

# Or via environment variable
export TEAMDAY_API_TOKEN="td_your_token_here"

Create PATs in the web app under Settings or see the API Keys Guide.

Logout

teamday auth logout

Characters

Characters are the rich persona entities in TeamDay — with identity, category, skills, marketing content, and more. Use the characters commands to manage them fully.

List Characters

teamday characters list

| id                   | name    | role              | category  | visibility | skills | mcps |
|----------------------|---------|-------------------|-----------|------------|--------|------|
| TQlbuEENel9U0vno6rWG | Joe     | Assistant         | general   | private    | 2      | 1    |
| D2LO3ld2ntuojvLsSlbU | Suzan   | Marketing Manager | marketing | private    | 3      | 0    |

Filter by category or visibility:

teamday characters list --category marketing
teamday characters list --visibility organization

Get Character Details

teamday characters get TQlbuEENel9U0vno6rWG

Shows the full profile: identity, capabilities (skills, MCPs, tools), marketing content (use cases, FAQ), and SEO metadata.

Use --format json to get the raw data for scripting.

Create Character

teamday characters create \
  --name "Sarah" \
  --role "SEO Analyst" \
  --category marketing \
  --system-prompt "You are an SEO specialist..." \
  --skills "core:research-assistant,core:data-analyst" \
  --visibility organization

Required options:

• --name — Character name
• --role — Role description
• --category — One of: marketing, finance, hr, engineering, operations, general, data
• --system-prompt — System prompt (use "$(cat prompt.txt)" for long prompts)

Optional:

• --slug — URL slug for the marketing page
• --description — Short character description
• --greeting — Initial greeting message
• --visibility — private | organization | public | unlisted (default: organization)
• --model — AI model
• --skills — Comma-separated skill IDs
• --mcps — Comma-separated MCP IDs
• --tags — Comma-separated tags
• --image — Avatar image URL

Update Character

teamday characters update TQlbuEENel9U0vno6rWG \
  --name "Sarah v2" \
  --skills "core:research-assistant,seo-analyzer"

All options from create are available. Only provided fields are updated.

Agents

Agents are the simplified interface for quick agent creation, execution, and chat. Both characters and agents operate on the same underlying entities, but agents expose fewer fields and add execution capabilities.

List Agents

teamday agents list

Filter options:

teamday agents list --status active
teamday agents list --visibility private
teamday agents list --tag code-review

Get Agent

teamday agents get <id>

Create Agent

teamday agents create \
  --name "Code Reviewer" \
  --role "Senior Developer" \
  --system-prompt "Review code for quality and security"

Required options:

• --name — Agent name
• --system-prompt — System prompt

Optional:

• --role — Role description (default: "Assistant")
• --model — AI model (default: claude-sonnet-4-6)
• --visibility — private | organization | public | unlisted (default: private)
• --mcps — MCP tools (comma-separated IDs)
• --tags — Tags (comma-separated)
• --based-on <id> — Clone an existing agent as a starting template

Update Agent

teamday agents update <id> --name "Updated Name" --role "New Role"

Delete (Archive) Agent

teamday agents delete <id>

Agents are soft-deleted (archived). Execution history is preserved.

Execute Agent

Send a single message and get a response:

teamday agents exec <id> "Review this PR for security issues"

Options:

• --space <id> — Execute in a workspace context
• --session <id> — Continue an existing conversation
• --chat <id> — Continue an existing chat
• --no-stream — Wait for complete response instead of streaming
• --timeout <ms> — Max execution time (default: 300000)

Interactive Chat

teamday agents chat <id>

Multi-turn conversation with streaming responses. Type exit or press Ctrl+C to quit.

Spaces

Spaces are workspaces where agents access files, tools, and collaborate. They hold installed MCPs, skills, agents, secrets, and files.

List Spaces

teamday spaces list

Get Space Details

teamday spaces get <id>

Shows the full space profile including installed resources:

Space: My Project
ID: abc123
Visibility: private

Resources:
Skills: core:research-assistant, seo-analyzer
MCPs: google-search, slack-bot
Agents: TQlbuEENel9U0vno6rWG
Secrets: OPENAI_API_KEY, SLACK_TOKEN

Use --format json for scripting.

Create Space

teamday spaces create --name "Backend API" --visibility private

Options:

• --name (required)
• --description
• --visibility — private | organization | public (default: private)
• --type — empty | git | starterKit (default: empty)
• --git-url — Repository URL (for type=git)
• --git-branch — Branch (default: main)
• --kit — Starter kit name (for type=starterKit)

Delete Space

teamday spaces delete <id>

Spaces are archived (soft delete), not permanently removed.

Install Resources

Add MCPs, skills, or agents to a space. Accepts multiple IDs at once:

# Add MCPs
teamday spaces add-mcp <spaceId> google-search slack-bot

# Add skills
teamday spaces add-skill <spaceId> core:research-assistant core:data-analyst

# Add agents (Characters installed as subagents)
teamday spaces add-agent <spaceId> TQlbuEENel9U0vno6rWG

Remove Resources

teamday spaces remove-mcp <spaceId> slack-bot
teamday spaces remove-skill <spaceId> core:data-analyst
teamday spaces remove-agent <spaceId> TQlbuEENel9U0vno6rWG

Manage Secrets

Secrets are encrypted environment variables available to agents running in the space.

# List secret keys (values are never shown)
teamday spaces secrets <spaceId>

# Set secrets (KEY=VALUE pairs)
teamday spaces set-secret <spaceId> OPENAI_API_KEY=sk-abc123 SLACK_TOKEN=xoxb-456

# Remove secrets
teamday spaces remove-secret <spaceId> OPENAI_API_KEY

Secret names must be UPPER_SNAKE_CASE. Values are encrypted at rest.

Chat in Space Context

Run an interactive chat session with an agent that has access to the space's files, MCPs, skills, and secrets:

teamday spaces chat <spaceId> --agent <agentId>

Chat Session: Sarah
   Role: SEO Analyst
   Space: abc123

   Type your message and press Enter
   Type "exit" or press Ctrl+C to quit

Browse Files

teamday spaces ls <spaceId> /
teamday spaces ls <spaceId> /src/

Git Operations

teamday spaces git <spaceId> status
teamday spaces git <spaceId> pull

MCPs

MCP (Model Context Protocol) instances give agents access to external tools and services. Browse your organization's MCP catalog.

List MCPs

teamday mcps list

| id     | name          | type           | active | credentials        | usage |
|--------|---------------|----------------|--------|--------------------|-------|
| mcp123 | Google Search | google-search  | Yes    | API_KEY            | 42    |
| mcp456 | Slack Bot     | slack          | Yes    | SLACK_TOKEN,APP_ID | 18    |

Get MCP Details

teamday mcps get <id>

Shows full configuration, permissions, credential status (values are masked), and usage stats.

Create MCP Instance

teamday mcps create \
  --type google-search \
  --name "My Google Search" \
  --description "Search integration for SEO team"

For credentials, pass JSON:

teamday mcps create \
  --type slack \
  --name "Slack Bot" \
  --credentials '{"SLACK_TOKEN": {"value": "xoxb-...", "isSecret": true}}'

Skills

Skills are reusable capabilities that agents can use. Browse available skills from core, your organization, and the marketplace.

List Skills

teamday skills list

Core Skills (5):
| id                      | name               | description                              |
|-------------------------|--------------------|------------------------------------------|
| core:research-assistant | research-assistant | Deep research using web search            |
| core:code-reviewer      | code-reviewer      | Review code for quality and security      |
| core:technical-writer   | technical-writer   | Write technical documentation             |
| core:data-analyst       | data-analyst       | Analyze data and generate insights        |
| core:pdf-handler        | pdf-handler        | Read and extract info from PDFs           |

Organization Skills (3):
| id    | name           | description                     |
|-------|----------------|---------------------------------|
| sk123 | seo-analyzer   | Analyze SEO performance         |
| sk456 | content-writer | Write blog posts and articles   |

Filter by source:

teamday skills list --source core
teamday skills list --source organization
teamday skills list --source marketplace

Tasks

Tasks are work items for tracking agent activities and multi-step processes.

List Tasks

teamday tasks list
teamday tasks list --status pending
teamday tasks list --assigned-to <agentId>
teamday tasks list --space <spaceId>
teamday tasks list --priority high

Create Task

teamday tasks create \
  --title "Review Q4 Report" \
  --description "Analyze Q4 sales data" \
  --priority high \
  --assigned-to <agentId>

Update Task

teamday tasks update <id> --status in_progress

Complete / Cancel

teamday tasks complete <id>
teamday tasks cancel <id>

Executions

Track agent execution history and manage running agents.

List Executions

teamday executions list
teamday executions list --status running
teamday executions list --agent <agentId>
teamday executions list --since 2025-01-01
teamday executions list --limit 100

Get Execution Details

teamday executions get <id>

Cancel Execution

teamday executions cancel <id>

Delegation Tree

View the full delegation tree when an agent delegates to sub-agents:

teamday executions tree <id>

Execution Logs

View detailed logs for a specific execution:

teamday executions logs <id>

Configuration

View All Settings

teamday config list

| Key      | Value                    |
|----------|--------------------------|
| api_url  | https://us.teamday.ai    |
| format   | table                    |
| timeout  | 300000                   |
| verbose  | false                    |

Set / Get / Reset

# Set a value
teamday config set api_url https://eu.teamday.ai
teamday config set format json
teamday config set timeout 600000

# Get a value
teamday config get api_url

# Reset one setting
teamday config unset format

# Reset everything
teamday config reset

Available Settings

Setting a default organization avoids passing --org to every keys command:

teamday config set organization org_456def

Environment Variables

Environment variables override config file settings:

export TEAMDAY_API_URL=https://us.teamday.ai
export TEAMDAY_API_TOKEN=td_your_token
export TEAMDAY_FORMAT=json
export TEAMDAY_NO_COLOR=1
export TEAMDAY_TIMEOUT=600000
export TEAMDAY_VERBOSE=true

Config file location: ~/.teamday/config.json

Claude API Keys

Manage the Claude API credentials that power your AI agents. TeamDay supports a 6-tier priority system for credential selection.

Check Credential Status

teamday keys status

  Claude Credential Status

  User-level:
    OAuth Token:  configured
    API Key:      not set

  Organization-level:
    Org: abc123
    OAuth Token:  not set
    API Key:      not set

  Active Tier:
    user-oauth

  Priority: user-oauth > user-api > org-oauth > org-api > server

Set Credentials

Four credential types are supported:

# Set your Claude subscription OAuth token
teamday keys set oauth sk-ant-oat01-your-token-here

# Set an Anthropic API key
teamday keys set api-key sk-ant-api03-your-key-here

# Set organization-level credentials (uses current org)
teamday keys set org-oauth sk-ant-oat01-org-token --org <orgId>
teamday keys set org-api-key sk-ant-api03-org-key --org <orgId>

Remove Credentials

teamday keys remove oauth
teamday keys remove api-key
teamday keys remove org-oauth --org <orgId>

Tier Priority

TeamDay selects credentials in priority order:

1. user-oauth — Your personal Claude subscription OAuth token
2. user-api — Your personal Anthropic API key
3. org-oauth — Organization-shared OAuth token
4. org-api — Organization-shared API key
5. server-oauth — TeamDay platform token (built-in)
6. server-api — TeamDay platform API key (built-in)

If a tier's token is suspended (e.g., insufficient credits), TeamDay automatically falls through to the next available tier.

Automation & Scripting

JSON Output

Use --format json on any command for machine-readable output:

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

# Count pending tasks
pending=$(teamday tasks list --status pending --format json | jq '.length')

Shell Script Example

#!/bin/bash
# setup-space.sh - Provision a fully configured space

SPACE_NAME="$1"

# Create space
result=$(teamday spaces create --name "$SPACE_NAME" --format json)
space_id=$(echo "$result" | jq -r '.space.id // .id')

# Install tools
teamday spaces add-mcp "$space_id" google-search
teamday spaces add-skill "$space_id" core:research-assistant core:data-analyst

# Set secrets
teamday spaces set-secret "$space_id" OPENAI_API_KEY="$OPENAI_API_KEY"

echo "Space $space_id ready"

CI/CD with PAT

# GitHub Actions example
jobs:
  check-agents:
    runs-on: ubuntu-latest
    env:
      TEAMDAY_API_TOKEN: ${{ secrets.TEAMDAY_TOKEN }}
      TEAMDAY_API_URL: https://us.teamday.ai
    steps:
      - name: Install CLI
        run: |
          git clone https://github.com/TeamDay-AI/teamday.git /tmp/teamday
          cd /tmp/teamday/packages/cli && bun install && bun link

      - name: Run agent
        run: |
          teamday agents exec $AGENT_ID "Generate the daily report" --no-stream

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

Command Reference

auth

characters

agents

spaces

mcps

skills

tasks

executions

keys

config

Troubleshooting

401 Unauthorized

teamday auth status     # Check if authenticated
teamday auth refresh    # Try refreshing token
teamday auth login      # Re-authenticate if refresh fails

Cannot connect to API

teamday config get api_url                        # Check current endpoint
teamday config set api_url https://us.teamday.ai  # Fix if wrong
teamday --api-url https://us.teamday.ai agents list  # Test with override

Agent execution errors (501)

Usually means no Claude API credential is configured. Check and set credentials via the CLI:

teamday keys status                              # Check what's configured
teamday keys set oauth sk-ant-oat01-your-token   # Set your Claude OAuth token
teamday keys set api-key sk-ant-api03-your-key   # Or set an API key

Or add one in the web app under Settings > Integrations.

Next Steps

• Create Your First Agent — Step-by-step walkthrough
• Spaces & Workspaces — Deep dive into workspace management
• API Keys & Authentication — Set up PATs for automation
• API Reference — Full endpoint documentation