cli AGENTS.md

Agent Guidance

Use this file when an agent is creating or maintaining Tripsy itinerary data through the local tripsy CLI or tripsy-mcp server.

CLI vs MCP

• Prefer tripsy-mcp when the client supports MCP. It exposes typed tools, structured results, safety annotations, and the same auth/config as the CLI.
• Use tripsy for direct terminal workflows, scripts, or when the current client cannot connect to MCP servers.
• MCP tool names use the tripsy_<resource>_<action> shape, for example tripsy_itinerary_guidance, tripsy_trips_create, tripsy_activities_create, and tripsy_collaborators_list.
• Use tripsy_raw_request only when no typed MCP tool covers a supported public Tripsy API route.

Authentication

• Do not print stored tokens unless the user explicitly asks for token output.
• Prefer the default TRIPSY_AUTH_BACKEND=auto; it uses OS credential storage when available.
• Use TRIPSY_AUTH_BACKEND=file only for headless automation or compatibility.
• Non-secret config is stored in credentials.json; tokens should be in the secure backend whenever one is available.

Itinerary Shape

• Set trip dates when planning a day-by-day itinerary.
• 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.
• Choose a destination-specific Unsplash image for leisure trips and set it as cover_image_url.
• Store 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.
• The images.unsplash.com path must be photo-<numeric timestamp>-<asset hash>. Do not store 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.
• Create one item per actual stop, reservation, meal, tour, or activity. Do not bundle multiple places into one activity.
• Use provider_reservation_code on activities, hostings, and transportations for the provider-issued reservation, confirmation, or booking code for that item.
• For transportation, keep transport_number for the flight, train, bus, or service number; use provider_reservation_code for the booking or confirmation code.
• Use start and end times when possible. Send all timed values as UTC ISO-8601 strings. Always set the local IANA timezone for the activity or lodging location, and departure_timezone/arrival_timezone for transportation endpoints.
• 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.
• Activity creation through MCP requires latitude and longitude; include address when known so the Tripsy map is populated.
• Add address, latitude, and longitude for lodging when known so the Tripsy map is populated.
• Use hostings for hotels/lodging. The lodging category slug is lodging.
• Use transportations for point-to-point movement and the transportation slugs listed below.
• Activities can use either a documented 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 that is not in 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.
• 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.