cli

# Tripsy CLI

`tripsy` is a command-line client for the public Tripsy API at `https://api.tripsy.app`. The project also ships `tripsy-mcp`, a Model Context Protocol server that exposes typed Tripsy tools for agents and MCP-capable apps.

API documentation is available at [docs.api.tripsy.app](https://docs.api.tripsy.app).

## What You Get

- Human-readable terminal output by default.
- JSON envelopes when output is piped or `--json` is passed.
- Raw JSON data with `--quiet`.
- Breadcrumbs that suggest useful next commands.
- A command catalog for humans and agents through `tripsy commands --json`.
- Secure token storage using the OS credential store when available, with explicit file fallback for automation.
- A local or hosted MCP server for structured agent workflows.

Agent-specific itinerary guidance does not belong in this README. Keep it in [AGENTS.md](./AGENTS.md) for repo-level agent instructions and [skills/tripsy/SKILL.md](./skills/tripsy/SKILL.md) for installable Codex skill guidance.

## Install

Install the latest GitHub release:

```sh
curl -fsSL https://tripsy.app/install_cli | bash
```

The installer downloads the latest release, verifies checksums, installs `tripsy` and `tripsy-mcp` into `~/.local/bin`, and adds that directory to your shell PATH when needed.

Install with Go:

```sh
go install github.com/tripsyapp/cli/cmd/tripsy@latest
go install github.com/tripsyapp/cli/cmd/tripsy-mcp@latest
```

Install a specific release:

```sh
curl -fsSL https://tripsy.app/install_cli | TRIPSY_VERSION=1.2.3 bash
```

Install into a custom directory:

```sh
curl -fsSL https://tripsy.app/install_cli | TRIPSY_BIN_DIR=/usr/local/bin bash
```

Build from a checkout:

```sh
make build
bin/tripsy --help
bin/tripsy-mcp --version
```

## Authenticate

Login with Tripsy credentials:

```sh
tripsy auth login --username you@example.com
```

Interactive password prompts hide typed input on terminals. Tokens are stored in the OS credential store when available. On macOS, Tripsy uses Keychain by default.

For automation, pass a token through `TRIPSY_TOKEN` or store one explicitly:

```sh
tripsy auth token set YOUR_TOKEN
```

Non-secret CLI config is stored at:

```text
~/.config/tripsy-cli/credentials.json
```

Environment overrides:

```sh
TRIPSY_TOKEN=...
TRIPSY_API_BASE=https://api.tripsy.app
TRIPSY_CONFIG_DIR=/custom/config/dir
TRIPSY_AUTH_BACKEND=auto|keychain|file
```

Use `TRIPSY_AUTH_BACKEND=file` only when you need file token storage for headless automation or compatibility.

## CLI Tools

Run `tripsy commands` for the current command catalog, or `tripsy commands --json` for agent-readable metadata.

| Command | Purpose | Subcommands |
| --- | --- | --- |
| `tripsy auth` | Authenticate and manage the stored API token. | `login`, `logout`, `status`, `token`, `reset-password`, `change-password` |
| `tripsy me` | Read or update the current Tripsy profile. | `show`, `update` |
| `tripsy trips` | List, create, inspect, update, and soft-delete trips. | `list`, `following`, `show`, `create`, `update`, `delete` |
| `tripsy hostings` | Manage hotel and lodging plans scoped to a trip. | `list`, `show`, `create`, `update`, `delete` |
| `tripsy activities` | Manage scheduled or unscheduled trip activities. | `list`, `show`, `create`, `update`, `delete` |
| `tripsy transportations` | Manage flights, trains, cars, and other transport. | `list`, `show`, `create`, `update`, `delete` |
| `tripsy expenses` | Manage trip expenses. | `list`, `show`, `create`, `update`, `delete` |
| `tripsy categories` | Manage custom activity categories. | `list`, `show`, `create`, `update`, `replace`, `delete` |
| `tripsy collaborators` | Manage trip guests and permissions. | `list`, `invite`, `update`, `delete` |
| `tripsy guests` | List account favorite guests and pending invitations. | `favorites` |
| `tripsy emails` | Manage alternative email addresses. | `list`, `add`, `delete` |
| `tripsy inbox` | Review automation emails that still need manual handling. | `list`, `show`, `update`, `delete` |
| `tripsy documents` | Get download URLs, move documents, attach links, upload files, and delete documents. | `get`, `update`, `attach`, `upload`, `delete` |
| `tripsy uploads` | Create raw backend-signed S3 upload URLs. | `create` |
| `tripsy request` | Make a raw Tripsy API request for routes without a friendly command. | none |
| `tripsy commands` | Print the CLI command catalog. | none |
| `tripsy doctor` | Check config, token presence, and authenticated API access. | none |
| `tripsy version` | Print the Tripsy CLI version. | none |

Common examples:

```sh
tripsy me show
tripsy trips list
tripsy trips following
tripsy trips create --name Italy --starts-at 2026-06-01 --ends-at 2026-06-15 --timezone Europe/Rome --cover-image-url "https://images.unsplash.com/photo-1529260830199-42c24126f198?ixlib=rb-4.1.0"
tripsy activities list --trip 42
tripsy activities create --trip 42 --name "Colosseum Tour" --activity-type tour --starts-at 2026-06-03T09:00:00Z --ends-at 2026-06-03T11:00:00Z --timezone Europe/Rome --address "Piazza del Colosseo, 1, 00184 Rome, Italy" --latitude 41.8902 --longitude 12.4922
tripsy hostings create --trip 42 --name "Hotel Eden" --starts-at 2026-06-01T14:00:00Z --ends-at 2026-06-05T11:00:00Z --timezone Europe/Rome
tripsy transportations create --trip 42 --name "Flight to Rome" --transportation-type airplane --departure-description JFK --arrival-description FCO
tripsy expenses create --trip 42 --title Dinner --price 78.5 --currency EUR --date 2026-06-03T20:00:00Z
tripsy categories create --name "Golf Clubs" --slug golf-clubs --icon-name golf --color AABBCC
tripsy documents upload boarding-pass.pdf --trip 42 --parent transportation:303
tripsy request GET /v1/me --json
tripsy doctor --verbose
```

Most trip subresource commands require `--trip <trip-id>` because the public API scopes those resources under a trip.

## Trip guests

```sh
tripsy collaborators list --trip 42
tripsy collaborators invite --trip 42 --email guest@example.com --read-only true
tripsy collaborators update 7 --trip 42 --can-edit false
tripsy collaborators delete 7 --trip 42
```

Collaborator lists combine all pages. The original `tripsy collaborators --trip 42` and `tripsy collaborators 42` list forms still work. Use user IDs from collaborators, not favorite or invitation record IDs.

Permission flags require explicit `true` or `false`. Both invite and update accept `--data` and `--set` for permission fields only, for example `collaborators update 7 --trip 42 --data '{"can_see_expenses":false}'`. Invitations use `read_only`; updates use `can_edit`. Both support `can_add_guests`, `can_see_expenses`, `can_edit_expenses`, `can_see_documents`, and `can_edit_documents`. Invitations also accept `title`; updates also accept `receive_notifications`; both support `is_travelling`. Omitted permissions retain invitation defaults or existing update values. To change your own travel or notification preference, send only that field. Broader permission changes require guest-management access; owners can change only their own travel or notification preference through this command.

For existing trips, use `collaborators invite`; the backend processes `guest_invites` only during trip creation. Successful invitation requests do not guarantee membership: confirmed favorites may be added immediately, other guests may remain pending, and unknown addresses may receive a generic success without an invitation. Check collaborators afterward. Removal revokes trip access and clears itinerary assignments.

MCP: `tripsy_collaborators_invite` takes `trip_id`, `invited_user_email`, and optional typed `permissions`; `tripsy_collaborators_update` takes `trip_id`, `user_id` (or `"me"`), and typed `permissions`; `tripsy_collaborators_delete` takes `trip_id` and `user_id`. Requires public routing for `/v1/guests/invite`, `/v1/trip/{trip_id}/collaborator/{user_id}`, and the latter's `/permissions` endpoint (exposure tracked in TRI-2153).

## Travel status

```sh
tripsy collaborators update me --trip 42 --is-travelling false
tripsy trips following
tripsy collaborators update me --trip 42 --is-travelling true
tripsy trips list
```

`me` resolves the authenticated user through `/v1/me`; an explicit user ID also works. Send `is_travelling` alone to change your own status, including as trip owner. `false` follows the trip without travelling; `true` restores it to the travelling list. MCP uses `tripsy_collaborators_update`:

```json
{"trip_id":"42","user_id":"me","permissions":{"is_travelling":false}}
```

This updates the existing collaborator permissions endpoint, not the trip metadata endpoint. It requires public routing for `PATCH /v1/trip/{trip_id}/collaborator/{user_id}/permissions`.

## Favorite guests

```sh
tripsy guests favorites
```

Lists all pages of account favorite guests and pending outgoing favorite invitations. Human output includes the user ID, name, email, and confirmed/pending status. JSON preserves the API response: `pending` distinguishes invitations from confirmed favorites, `favorite_user.id` is the user ID, and the top-level `id` is a favorite or invitation record ID.

MCP: `tripsy_guests_favorites_list` takes no arguments and returns the same records. Requires public routing for `GET /v1/guests/favorites`.

## Output

When output is piped, or when `--json` is passed, commands emit an envelope:

```json
{
  "ok": true,
  "data": {},
  "summary": "Current user",
  "breadcrumbs": [
    {
      "action": "show",
      "cmd": "tripsy trips show <id>"
    }
  ]
}
```

Use `--quiet` to print raw JSON data only.

## MCP Server

Use Tripsy's MCP server when an agent or app supports MCP. Prefer MCP for model-driven workflows because tools expose names, descriptions, schemas, structured results, and safety annotations.

### Hosted Endpoint

Tripsy operates a public MCP server at `https://mcp.tripsy.app`. OAuth-capable clients such as Claude and ChatGPT can connect directly without installin