tripsy

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.