tripsy

name	tripsy
description	Use when an agent needs to inspect, create, update, or organize Tripsy data through the local tripsy CLI or tripsy-mcp server.

Tripsy CLI Agent Skill

Use this skill when an agent needs to inspect, create, update, or organize Tripsy data through the local tripsy CLI or tripsy-mcp server.

The CLI and MCP server talk to the public Tripsy API at https://api.tripsy.app. Public API paths do not include an /api prefix.

Operating Rules

• Prefer tripsy-mcp typed tools when the current client supports MCP.
• Prefer friendly CLI commands over tripsy request when a wrapper exists.
• Use --json for agent-readable output. Use --quiet only when raw data is needed without the envelope.
• Read the ok, summary, data, and breadcrumbs fields from JSON envelopes.
• Follow breadcrumbs when navigating related resources.
• Do not print stored tokens unless the user explicitly asks for token output.
• Do not ask the user for passwords in chat. Ask them to run tripsy auth login --username USERNAME locally, or use TRIPSY_TOKEN.
• Use exact ISO-8601 UTC datetimes for every timed value, for example 2026-06-03T09:00:00Z. Always pair them with the relevant local IANA timezone field (timezone, departure_timezone, or arrival_timezone).
• When displaying activity or lodging dates/times from MCP data, convert UTC starts_at and ends_at into the item's timezone before formatting local date/time.
• When displaying transportation dates/times from MCP data, convert UTC departure_at with departure_timezone and UTC arrival_at with arrival_timezone; do not apply one endpoint's timezone to the other endpoint unless the fields explicitly match.
• For trip dates, use date strings such as 2026-06-01.
• trips list returns trips where the authenticated user is travelling. Use trips following for trips the user follows but is not travelling on.
• has_dates is authoritative. If has_dates is false, ignore starts_at and ends_at even when those fields are present.
• When creating a destination trip, choose a beautiful destination-specific Unsplash image and set it as cover_image_url.
• Use a real direct Unsplash CDN URL copied from an image result, in the form https://images.unsplash.com/photo-1562869929-bda0650edb1f?ixid=...&ixlib=rb-4.1.0. Tripsy will add the needed rendering parameters.
• The images.unsplash.com path must be photo-<numeric timestamp>-<asset hash>. Do not use the Unsplash page URL, and do not turn short photo IDs like nWdsya5_Yms into https://images.unsplash.com/photo-nWdsya5_Yms.
• Before saving a trip cover_image_url, validate that it is a real direct Unsplash CDN URL. If the client has external URL access, also confirm the image URL is reachable and not returning a 404.
• For itinerary planning, set trip dates whenever day-by-day timed planning is needed. If the user did not provide dates but asks for a planned itinerary, choose explicit reasonable dates and state them.
• Create one item per actual stop, reservation, meal, tour, or activity. Do not create one activity that bundles a full day or multiple places.
• Set latitude and longitude for every activity; MCP rejects activity creation without both coordinates so Tripsy's map is populated.
• Set latitude and longitude for every known hosting and transportation point so Tripsy's map is populated.
• Use the most specific supported category slug for Activity activity_type; do not default to general or tour when a better category exists.
• Activities can use either a built-in activity_type slug or a visible custom category slug. Custom category slugs are only valid on Activity objects through activity_type; do not use them for lodging, transportation, expenses, or trips. If an activity has an activity_type outside the built-in list, fetch visible custom categories through tripsy_categories_list or tripsy categories list and resolve the slug there before displaying the category name, icon, or color.
• Use hostings for hotels/lodging. The lodging category slug is lodging.
• Use transportations for point-to-point movement such as flights, trains, cars, buses, cruises, ferries, roadtrips, walks, and similar travel.
• For flights, create a transportation with transportation_type set to airplane, set departure_description and arrival_description to the airport IATA codes, include each airport's latitude and longitude, and omit name unless the user provided one.
• For transfer activities, create a transportation with transportation_type set to roadtrip, and fill both departure and arrival locations with name/description, address, latitude, and longitude.
• Delete operations can be executed when requested. Tripsy deletes are recoverable, so they can be undone if necessary. State what will be deleted before running the command when the user has not already been explicit.

Avoid these common itinerary mistakes:

• Do not use unsplash.com/photos/... as cover_image_url.
• Do not invent or transform Unsplash photo IDs into images.unsplash.com URLs; copy the real numeric photo asset URL.
• Do not save a malformed cover_image_url; check for 404 only when the client has external URL access.
• Do not create one activity named "Day 1 itinerary" or similar that contains multiple stops.
• Do not put hotels or lodging into activities.
• Do not put transfers into activities.
• Do not omit coordinates when a location is known.
• Do not treat an unknown Activity activity_type as invalid until you have checked whether it is a visible custom category. Do not invent ad hoc values such as sightseeing.

MCP Server

Use MCP when available because tools expose schemas, descriptions, safety annotations, and structured results without requiring shell command composition.

MCP tool inputs follow the same itinerary rules as the CLI: timed fields are UTC, timezone fields carry the local display timezone, trip cover URLs must be direct Unsplash CDN URLs, and delete tools can be used when requested because deletes can be undone if necessary. MCP clients that display itinerary data must convert activity and lodging starts_at/ends_at values into timezone, transportation departure_at into departure_timezone, and transportation arrival_at into arrival_timezone before formatting local dates/times.

Common tool names:

tripsy_status
tripsy_itinerary_guidance
tripsy_trips_create
tripsy_activities_create
tripsy_hostings_create
tripsy_transportations_create
tripsy_expenses_create
tripsy_collaborators_list
tripsy_raw_request

Use tripsy_raw_request only for supported public API routes without a typed MCP tool. The raw MCP tool accepts Tripsy API paths such as /v1/me, not arbitrary external URLs.

Discovery

Start each unfamiliar workflow with structured command discovery:

tripsy commands --json
tripsy trips --help --agent --json
tripsy activities --help --agent --json

Check the installed version:

tripsy --version
tripsy version --json

Run health checks:

tripsy doctor --json
tripsy doctor --verbose --json

Authentication

Check auth before authenticated work:

tripsy auth status --json

If unauthenticated, ask the user to run one of:

tripsy auth login --username USERNAME
tripsy auth token set TOKEN

Environment overrides:

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

Token storage:

• auto is the default. It uses OS credential storage when available and falls back to file storage where no supported secure backend exists.
• keychain requires an OS credential backend. On macOS this uses Keychain through the system security tool.
• file stores the token in credentials.json with 0600 permissions and is intended for headless automation or compatibility.
• Non-secret config such as base_url remains in credentials.json.
• Legacy plaintext tokens are migrated out of credentials.json when a secure backend is available.

Logout:

tripsy auth logout --json
tripsy auth logout --local --json

Output Handling

Most JSON output has this shape:

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

For list endpoints, data.results contains items. Trip, hosting, activity, and transportation read commands use the lean v2 API and combine paginated results before rendering. Trip results are split by current-user travelling status: trips list returns travelling trips and trips following returns followed-only trips.

For detail commands in human output, the CLI displays all fields returned by the API. For agents, prefer --json and inspect data directly.

Common Flags

Global flags:

--json
--quiet
--api-base URL
--token TOKEN
--config-dir DIR

List filters where supported:

--fields id,name,starts_at
--updated-since 2026-03-17T00:00:00Z
--deleted

Mutation payload options:

--data '{"name":"Italy","timezone":"Europe/Rome"}'
--set key=value
--name Italy
--starts-at 2026-06-01

Field flags use kebab-case and map to API snake_case, for example --starts-at maps to starts_at.

Account

Show current profile:

tripsy me show --json

Update profile:

tripsy me update --name "Updated Name" --timezone America/Sao_Paulo --default-currency USD --json

Useful profile fields include name, username, email, language, timezone, default_currency, store_currency, calendar preferences, notification preferences, and photo_url.

Trips

List trips:

tripsy trips list --json
tripsy trips following --json
tripsy trips list --fields id,name,starts_at,ends_at,timezone --json

Show full trip details:

tripsy trips show TRIP_ID --json

Create a trip:

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-1562869929-bda0650edb1f?ixid=...&ixlib=rb-4.1.0" --json

Update a trip:

tripsy trips update TRIP_ID --description "Summer vacation" --json
tripsy trips update TRIP_ID --set cover_gradient=3 --json

Delete a trip:

tripsy trips delete TRIP_ID --json

Common trip fields: name, timezone, hidden, description, starts_at, ends_at, cover_gradient, cover_image_url, has_dates, number_of_days, and guest_invites.

Trip ownership and dates:

• trips list returns trips where the authenticated user is travelling.
• trips following returns trips the authenticated user follows but is not travelling on.
• has_dates is authoritative. If has_dates is false, ignore starts_at and ends_at even when those fields are present.

Trip covers:

• Prefer a destination-specific Unsplash image for leisure trips.
• Use the direct images.unsplash.com image URL copied from the actual image result, including Unsplash metadata query parameters such as ixid and ixlib.
• Valid cover URLs use the photo-<numeric timestamp>-<asset hash> path format, for example photo-1562869929-bda0650edb1f; short ID paths such as photo-nWdsya5_Yms are invalid.
• If the client has external URL access, confirm the final cover_image_url is reachable and not returning 404 before saving it on the trip.
• Do not add crop, width, quality, or format parameters unless the user explicitly asks; the Tripsy app derives the right display parameters.

Itinerary Resources

All trip subresources require --trip TRIP_ID.

Itinerary Planning

Tripsy works best when the itinerary is structured as separate timed items:

• Use one activity per place or experience, for example separate records for a museum, lunch, park, and evening event.
• Avoid day-summary activities such as "Day 1: Museum, Lunch and Park" unless the user explicitly asks for a note-style summary.
• Prefer start and end times for activities. Store every timed value as a UTC ISO-8601 string and set the local timezone for the activity location.
• Include latitude and longitude for every activity, and include address when known.
• Use hostings for hotels/lodging and transportations for transport segments instead of forcing them into activities.

Golden path payload shape:

{
  "trip": {
    "name": "Rome",
    "timezone": "Europe/Rome",
    "starts_at": "2026-06-01",
    "ends_at": "2026-06-05",
    "cover_image_url": "https://images.unsplash.com/photo-1529260830199-42c24126f198?ixlib=rb-4.1.0"
  },
  "hosting": {
    "name": "Hotel Eden",
    "starts_at": "2026-06-01T14:00:00Z",
    "ends_at": "2026-06-05T11:00:00Z",
    "timezone": "Europe/Rome",
    "address": "Via Ludovisi 49, 00187 Rome, Italy",
    "latitude": 41.9081,
    "longitude": 12.4882
  },
  "activity": {
    "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
  },
  "transfer": {
    "name": "Transfer to Hotel Eden",
    "transportation_type": "roadtrip",
    "departure_description": "Rome Fiumicino Airport",
    "departure_address": "Via dell'Aeroporto di Fiumicino, 00054 Fiumicino RM, Italy",
    "departure_latitude": 41.8003,
    "departure_longitude": 12.2389,
    "arrival_description": "Hotel Eden",
    "arrival_address": "Via Ludovisi 49, 00187 Rome, Italy",
    "arrival_latitude": 41.9081,
    "arrival_longitude": 12.4882
  }
}

Activity category slugs:

concert, fit, general, kids, museum, note, relax, restaurant, shopping,
theater, tour, event, meeting, bar, cafe, parking, amusementPark, aquarium,
atm, bakery, bank, beach, brewery, campground, evCharger, fireStation,
fitnessCenter, foodMarket, gasStation, hospital, laundry, library, marina,
movieTheater, nationalPark, nightlife, park, pharmacy, police, postOffice,
publicTransport, restroom, school, stadium, university, winery, zoo

Special category/resource handling:

lodging

Use lodging for hotel/lodging category semantics, but create actual lodging records through tripsy hostings.

Transportation category slugs:

airplane, bike, bus, car, roadtrip, cruise, ferry, motorcycle, train, walk

Use these slugs with transportation_type on tripsy transportations.

For flights, use airplane, put the airport IATA codes in departure_description and arrival_description, include departure_latitude, departure_longitude, arrival_latitude, and arrival_longitude for the airports, and omit name unless the user provided one.

Activities:

tripsy activities list --trip TRIP_ID --json
tripsy activities list --trip TRIP_ID --activity-type museum --json
tripsy activities show --trip TRIP_ID ACTIVITY_ID --json
tripsy activities create --trip TRIP_ID --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, Rome, Italy" --latitude 41.8902 --longitude 12.4922 --json
tripsy activities update --trip TRIP_ID ACTIVITY_ID --notes "Bring tickets" --checked true --json
tripsy activities delete --trip TRIP_ID ACTIVITY_ID --json

Useful activity fields: activity_type, period, starts_at, ends_at, all_day, name, description, phone, website, checked, address, longitude, latitude, notes, timezone, provider_reservation_code, price, currency, and assigned_users.

Use provider_reservation_code for the provider-issued reservation, confirmation, or booking code for the activity, such as a tour confirmation number or restaurant booking code.

When displaying activities, convert UTC starts_at and ends_at into the activity timezone before formatting local date/time. Resolve activity_type against the built-in activity category slugs first. If the slug is not built in, fetch visible custom categories through tripsy_categories_list or tripsy categories list and use the matching custom category metadata so the UI shows the correct category name, icon, and color. Custom category slugs only apply to Activity objects and must not be reused for other Tripsy resource types.

Hostings:

tripsy hostings list --trip TRIP_ID --json
tripsy hostings show --trip TRIP_ID HOSTING_ID --json
tripsy hostings create --trip TRIP_ID --name "Hotel Eden" --starts-at 2026-06-01T14:00:00Z --ends-at 2026-06-05T11:00:00Z --timezone Europe/Rome --address "Via Ludovisi 49, Rome, Italy" --latitude 41.9081 --longitude 12.4882 --json
tripsy hostings update --trip TRIP_ID HOSTING_ID --room-number 402 --json

Useful hosting fields: starts_at, ends_at, timezone, name, description, address, longitude, latitude, phone, room_type, room_number, website, notes, provider_reservation_code, price, currency, and assigned_users.

Use provider_reservation_code for the provider-issued lodging reservation, confirmation, or booking code, such as a hotel confirmation number.

Transportations:

tripsy transportations list --trip TRIP_ID --json
tripsy transportations list --trip TRIP_ID --transportation-type airplane --json
tripsy transportations show --trip TRIP_ID TRANSPORTATION_ID --json
tripsy transportations create --trip TRIP_ID --name "Flight to Rome" --transportation-type airplane --departure-description JFK --departure-at 2026-05-31T22:30:00Z --departure-timezone America/New_York --departure-latitude 40.6413 --departure-longitude -73.7781 --arrival-description FCO --arrival-at 2026-06-01T10:30:00Z --arrival-timezone Europe/Rome --arrival-latitude 41.8003 --arrival-longitude 12.2389 --json

Useful transportation fields: transportation_type, departure_description, departure_at, departure_timezone, departure_address, departure_longitude, departure_latitude, arrival_description, arrival_at, arrival_timezone, arrival_address, arrival_longitude, arrival_latitude, company, seat_number, seat_class, transport_number, provider_reservation_code, terminal, gate, price, currency, and assigned_users.

Use provider_reservation_code for provider-issued transportation reservation, confirmation, or booking codes. Keep transport_number for the flight, train, bus, or service number.

When displaying transportations, convert UTC departure_at with departure_timezone and UTC arrival_at with arrival_timezone before formatting local endpoint dates/times. Do not apply the departure timezone to arrival times or the arrival timezone to departure times unless those fields explicitly match.

For transfer activities, create a transportation with transportation_type set to roadtrip, and include departure and arrival names/descriptions, addresses, latitudes, and longitudes.

Expenses:

tripsy expenses list --trip TRIP_ID --json
tripsy expenses show --trip TRIP_ID EXPENSE_ID --json
tripsy expenses create --trip TRIP_ID --title Dinner --price 78.5 --currency EUR --date 2026-06-03T20:00:00Z --json
tripsy expenses update --trip TRIP_ID EXPENSE_ID --price 82 --json

Expense fields: title, date, price, and currency.

Move an itinerary item to another trip:

tripsy activities update --trip OLD_TRIP_ID ACTIVITY_ID --update-trip NEW_TRIP_ID --json
tripsy hostings update --trip OLD_TRIP_ID HOSTING_ID --update-trip NEW_TRIP_ID --json
tripsy transportations update --trip OLD_TRIP_ID TRANSPORTATION_ID --update-trip NEW_TRIP_ID --json

Collaborators

List collaborators and pending invitations:

tripsy collaborators --trip TRIP_ID --json

Inspect permissions in the returned data before assuming a user can edit expenses or restricted resources.

Email Addresses

List alternative emails:

tripsy emails list --json

Add an alternative email:

tripsy emails add [e-mail] --json

Delete an alternative email:

tripsy emails delete EMAIL_ID --json

Automation Inbox

List unprocessed automation emails:

tripsy inbox list --json

Show an inbox email:

tripsy inbox show EMAIL_ID --json

Rename or move an email:

tripsy inbox update EMAIL_ID --subject "Renamed itinerary email" --json
tripsy inbox update EMAIL_ID --trip-id TRIP_ID --json
tripsy inbox update EMAIL_ID --activity-id ACTIVITY_ID --json
tripsy inbox update EMAIL_ID --hosting-id HOSTING_ID --json
tripsy inbox update EMAIL_ID --transportation-id TRANSPORTATION_ID --json

Only one move target is applied. API priority is trip, activity, hosting, then transportation.

Raw Requests

Use raw requests only when the friendly command surface does not cover an API route or flag yet.

tripsy request GET /v1/me --json
tripsy request GET /v1/trips --query fields=id,name --json
tripsy request PATCH /v1/me --data '{"timezone":"Europe/Rome"}' --json

For request bodies, use --data with a JSON object or repeated --set key=value.

Installation

Install with the release script:

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

Install a specific version:

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

Install from source with Go:

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

Verify:

tripsy --version
tripsy-mcp --version
tripsy doctor --json

Error Handling

• 401 usually means missing/invalid auth or failed public auth flow.
• 403 means authenticated but not allowed to edit or view the target.
• 404 means not found or not owned/accessible by the current user.
• 400 means validation failure; inspect the JSON error body.
• If a command has no friendly wrapper, use tripsy request.