Save this content to: .claude/skills/there-there/SKILL.md

---
package: spatie/there-there-cli
source_path: skills/there-there/SKILL.md
repo: https://github.com/spatie/there-there-cli
---

---
name: there-there
description: >-
  Manage There There helpdesk tickets, contacts, and channels using the
  there-there CLI. Use when the user wants to list, view, reply to, search,
  or manage tickets; assign team members; manage tags; view contacts; or
  interact with there-there.app from the command line.
license: MIT
metadata:
  author: spatie
  version: "0.0.1"
---

# There There CLI

The `there-there` CLI lets you manage [There There](https://there-there.app) helpdesk tickets from the terminal. Every There There API endpoint has a corresponding command.

## Prerequisites

Check that the CLI is installed:

```bash
there-there --version
```

If not installed:

```bash
composer global require spatie/there-there-cli
```

Ensure Composer's global bin directory is in `PATH`:

```bash
composer global config bin-dir --absolute
```

## Authentication

```bash
# Log in (automatically creates a profile named after your workspace)
there-there login

# Log in with a specific profile name
there-there login --profile=spatie

# Log out the active profile
there-there logout
```

Get your API token from your workspace settings at https://there-there.app/settings/account/api-tokens.

If any command returns a 401 error, the token is invalid or expired. Run `there-there login` again.

## Profiles

The CLI supports multiple profiles for users with access to multiple workspaces.

```bash
# Log in to multiple workspaces
there-there login --profile=spatie
there-there login --profile=ohdear

# List all profiles
there-there profiles

# Switch the default profile
there-there use spatie

# Run a single command against a different profile
there-there list-tickets --profile=ohdear
```

When logging in without `--profile`, the profile is automatically named after the workspace (slugified). All commands accept `--profile` to override the active profile for that invocation.

## Quick command reference

All commands output JSON. See [references/commands.md](references/commands.md) for full parameter details.

### User & workspace

```bash
# Who am I? Returns user and workspace info
there-there get-me
```

### Tickets

```bash
# List all tickets (paginated)
there-there list-tickets

# Filter by status
there-there list-tickets --filter-status=open

# Filter by channel or tags
there-there list-tickets --filter-channel-ulids=CHANNEL_ULID --filter-tag-ulids=TAG_ULID1,TAG_ULID2

# Only my tickets
there-there list-tickets --filter-assigned-to-me=true

# Sort by most recent activity
there-there list-tickets --sort=-updated_at

# View a specific ticket with messages and activities
there-there show-ticket --ticket=01HX9F3K2M...

# Semantic search (AI-powered, finds tickets by meaning)
there-there list-tickets --q="how do I get a refund"

# Full-text keyword search
there-there list-tickets --filter-search="refund"

# Filter by specific assignee
there-there list-tickets --filter-assigned-user-ulid=USER_ULID

# Filter by date range
there-there list-tickets --filter-created-after=2026-01-01 --filter-created-before=2026-02-01

# Combine search with filters
there-there list-tickets --q="billing issue" --filter-status=open --filter-created-after=2026-01-01
```

### Ticket actions

```bash
# Change status
there-there update-ticket-status --ticket=ULID --field status=closed

# Assign to a user
there-there update-ticket-assignee --ticket=ULID --field assignee_ulid=USER_ULID

# Unassign
there-there update-ticket-assignee --ticket=ULID --field assignee_ulid=null

# Assign to a team
there-there update-ticket-team --ticket=ULID --field team_ulid=TEAM_ULID

# Add a tag
there-there add-tag-to-ticket --ticket=ULID --tag=TAG_ULID

# Remove a tag
there-there remove-tag-from-ticket --ticket=ULID --tag=TAG_ULID
```

### Messages

```bash
# Reply to a ticket
there-there reply-to-ticket --ticket=ULID --field body="<p>Thanks for reaching out!</p>"

# Forward a ticket
there-there forward-ticket --ticket=ULID --field body="<p>FYI</p>" --field to_recipients='["someone@example.com"]'

# Add an internal note
there-there add-note-to-ticket --ticket=ULID --field body="<p>Internal note here</p>"
```

### Activities

```bash
# List activities for a ticket
there-there list-ticket-activities --ticket=ULID
```

### Tags, channels, members, contacts

```bash
# List workspace tags
there-there list-tags

# List workspace channels
there-there list-channels

# List workspace members
there-there list-members

# List contacts (with search/filter)
there-there list-contacts --filter-search=john

# View a specific contact
there-there show-contact --contact=ULID
```

### Pagination

All list commands support pagination:

```bash
there-there list-tickets --page=2 --per-page=10
```

## Common workflows

### Ticket triage

List open tickets, review them, and take action. See [references/workflows.md](references/workflows.md) for the full triage workflow.

Quick version:

```bash
# 1. List open tickets sorted by most recent
there-there list-tickets --filter-status=open --sort=-updated_at

# 2. View a ticket to read messages
there-there show-ticket --ticket=ULID

# 3. Reply to the customer
there-there reply-to-ticket --ticket=ULID --field body="<p>Your reply here</p>"

# 4. Close resolved tickets
there-there update-ticket-status --ticket=ULID --field status=closed
```

### Searching tickets

The `list-tickets` command supports two types of search plus date and assignee filters:

- **`--q`** (semantic search): Uses AI embeddings to find tickets by meaning, not just keywords. Matches across subjects, summaries, and message content. Results are ordered by relevance. Requires AI to be enabled for the workspace (returns 422 if not). Can be combined with all other filters.
- **`--filter-search`** (full-text search): Keyword search across ticket subjects, messages, and contact info. Faster than semantic search, good for finding exact terms or email addresses.
- **`--filter-assigned-user-ulid`**: Filter by a specific user ULID (use `list-members` to find ULIDs). Different from `--filter-assigned-to-me` which uses the authenticated user.
- **`--filter-created-after`**: Only return tickets created on or after this date. ISO 8601 format (e.g. `2026-01-01`).
- **`--filter-created-before`**: Only return tickets created on or before this date. ISO 8601 format (e.g. `2026-03-01`).

All filters can be combined. When `--q` is used without an explicit `--sort`, results are ordered by relevance. When `--q` is used with `--sort`, the explicit sort takes precedence.

```bash
# Semantic search for tickets about a topic
there-there list-tickets --q="how do I get a refund"

# Full-text search for a keyword
there-there list-tickets --filter-search="invoice"

# Combine semantic search with filters
there-there list-tickets --q="billing issue" --filter-status=open --filter-created-after=2026-01-01

# Tickets from a specific user in a date range
there-there list-tickets --filter-assigned-user-ulid=USER_ULID --filter-created-after=2026-01-01 --filter-created-before=2026-02-01
```

### Bulk operations

```bash
# Find all unassigned tickets
there-there list-tickets --filter-unassigned=true

# Assign them
there-there update-ticket-assignee --ticket=ULID --field assignee_ulid=USER_ULID
```

## Output format

All commands return JSON. When presenting results to the user:

- **Tickets**: Show as a table with columns: subject, status, channel, assignee, tags, last message preview, updated at.
- **Messages**: Show sender, type (inbound/outbound/note), body preview, attachments count, inline-image count, timestamp.
- **Inline images**: Customer-pasted screenshots come back on each message under `inline_images[]`. Their `url` and `download_url` need the same Bearer token as the API; see [references/commands.md](references/commands.md#show-ticket) for a `curl` snippet.
- **Contacts**: Show name, email, ticket count, last activity.
- **Activities**: Show type, user, description, timestamp.