Voyagier

@voyagier/cli

Plan, price and book real trips from your terminal. Everything syncs to voyagier.com.

The CLI is a shell for the Voyagier MCP server: one command per tool. Every trip-planning command is one MCP tool — voyagier -- — built at runtime from the server's tool list at https://mcp.voyagier.com/api/mcp. The same tools power claude.ai, Claude Desktop and every other MCP client, so there is one implementation of every verb and a tool published on the server shows up in your terminal without an upgrade. For hosts that only speak stdio, voyagier mcp is a proxy for the same server.

npm install -g voyagier             # or the canonical package: @voyagier/cli

voyagier auth login # browser flow; keeps the token out of shell history voyagier doctor # credentials, MCP connection, tool count, version voyagier mcp install claude-code # point an MCP client at the hosted server (also: cursor, claude-desktop) voyagier update # later: bring a global install to the latest release

voyagier is a convenience alias that tracks the latest compatible @voyagier/cli release. Pinning an exact version? Use the canonical package: npm install -g @voyagier/cli@ .

No install permissions (sandboxed agent, CI)? Every command works zero-install via npx:

VOYAGIER_TOKEN=<your-token> npx @voyagier/cli doctor --json

Quick Start

A trip plan is a goal graph: the plan ships with goals (flights, hotel, dates, destination, travellers) and you compose the trip by exploring inventory, promoting a search onto a goal, and selecting options. Searches are asynchronous — poll until the status is terminal.

# 1) Find or create the client

voyagier list_clients --query "Doe" --json voyagier create_client --name "Doe Family" --client_type Individual --email "doe@example.com" --json

2) Resolve the destination, then scaffold the plan with its party

voyagier search_destinations --query "Lisbon" --json voyagier create_plan --client_id --title "Doe — Lisbon" \ --travel_destination_id --start_date 2026-11-20 --end_date 2026-11-27 \ --travellers '[{"first_name":"Jane","last_name":"Doe","type":"Adult"}]' --json

3) Explore flights (no plan is touched), poll, then promote the result onto the plan's goal

voyagier search_flights --from BWI --to LIS --date 2026-11-20 --return 2026-11-27 voyagier get_search_status --search_id voyagier promote_search --plan_id --search_id --goal_id --json

4) Options → pick

voyagier get_options --selection_id voyagier select_option --option_id --json

5) Readiness, quote, book at exactly the quoted price

voyagier get_plan_status --plan_id voyagier get_plan_quote --plan_id voyagier book_plan --plan_id --expect_total_cents --item_ids --json

Not sure which tool? Ask the server.

voyagier search_tools --query "hotel dates" --json voyagier get_tool_details --name set_hotel_dates --json

voyagier --help prints the server's description of the tool and one flag per input, with types and required-ness.

How the command surface works

• `voyagier --help` lists the local commands and one command per tool the server publishes.
• Flags mirror the tool's input schema. plan_id is --plan_id; required inputs are required flags. Strings, integers, numbers, booleans (--force / --force false), enums (allowed values in --help), arrays (--item_ids a b, or repeat the flag) and JSON literals for objects (--travellers '[…]'; --help lists the object's keys, required ones starred, with their types and descriptions). Flags whose schema allows null (marked (pass null to clear) in --help) also take the literal null, sent as JSON null: voyagier update_plan --plan_id --cover_media_id null clears the cover photo. Every repeatable array flag has a --no- companion that sends the empty list [] — the server's own "pass an empty list to clear" where a tool defines it: voyagier get_search_status --search_id --no-airlines reads the stored search with its airline filter cleared. Property or item schemas written as a local $ref into the tool's own schema are resolved before the flag is typed, so they behave like their target.
• Output. --json prints the tool's result as JSON: the payload object itself, with no wrapper key. Without it, get_plan_status, search_flights / search_hotels / search_activities / get_search_status / promote_search, get_options, get_plan_itinerary and get_plan_quote render a compact human view; every other tool (including search_destinations, search_tools and refresh_options) pretty-prints the JSON.
• Errors use one envelope everywhere: { "error": true, "code", "message", "details"? }, exit 1. AUTH_FAILED, PERMISSION_DENIED, RATE_LIMITED (with details.retryAfterSeconds), VALIDATION, NOT_FOUND (unknown command or tool), API_ERROR (the tool's own error text), NETWORK, COMMAND_REMOVED, STATE_CORRUPT (mcp install found an unreadable client config). The table with recovery steps is in AGENT.md.
• Tool cache. The server's tool list is cached in ~/.voyagier/tools-cache.json for one hour; the next tool command after that refreshes it, and so do voyagier doctor and running a tool name the cache does not know yet (voyagier --help alone prints the cached list without a fetch). doctor and --verbose report a stable hash of the tool surface (names + input schemas) so scripts can detect a contract change.
• Agent substrate. Non-interactive; under --json stdout carries exactly one JSON document (diagnostics, spinners and warnings go to stderr); stable exit codes (0 / 1 handled / 2 unexpected); absolute timestamps in rendered output.

Commands

Every 3.x trip-planning command (plan-trip, search flights, select, plans …, clients …, …) is replaced by a tool. Running one prints the replacement and exits 1; the full table is in the CHANGELOG.

For AI Agents

voyagier agent-docs            # the MCP server's guidance, then the CLI usage notes (AGENT.md)

npx @voyagier/cli agent-docs # zero-install variant

The first part is the server's own instructions (the trip-planning guidance: tool order, how searches complete, how booking is gated), the same text every MCP client receives. The second part is AGENT.md: the tool model, flag typing, JSON shapes, the error code table and the 3.x migration.

Connect an AI agent

Voyagier runs a hosted MCP server at https://mcp.voyagier.com/api/mcp. It is the recommended way for AI agents and assistants to use Voyagier: the client connects over HTTP with your Personal Access Token and gets the whole tool surface, with no local install to manage. The CLI itself is the same surface for command-line workflows, scripting and CI.

voyagier mcp install sets this up in one step:

voyagier mcp install claude-code      # writes ./.mcp.json (--global writes ~/.claude.json)

voyagier mcp install cursor # writes ~/.cursor/mcp.json (--project writes ./.cursor/mcp.json) voyagier mcp install claude-desktop # writes claude_desktop_config.json

It uses your saved token (voyagier login), merges a voyagier entry into the client's existing config, and leaves every other server in that file untouched. Pass --dry-run to see the resolved path and the exact entry before anything is written, or --token to install a specific token. The token is masked in all output and is only ever written into the config file. Restart the client afterwards to pick up the change.

Claude Desktop's config format describes stdio servers only, so that client is pointed at the CLI's local server (voyagier mcp) instead. Voyagier can also be added through the remote connectors section of the app settings, which uses the hosted endpoint directly.

Stdio MCP proxy

For hosts that only speak stdio, the CLI ships an MCP stdio server that is a proxy for the hosted server:

voyagier mcp          # stdio proxy (JSON-RPC on stdout)

It has no tool table of its own. tools/list and tools/call are forwarded to https://mcp.voyagier.com/api/mcp (or VOYAGIER_MCP_URL) with the token from VOYAGIER_TOKEN or the saved credentials, and the results are returned exactly as the server sent them, so the proxy always exposes the server's current tools. The server's instructions are passed through on initialize. When the server cannot be reached, the proxy still completes the local handshake and explains the problem in instructions; each request then returns a JSON-RPC error that names the fix (set VOYAGIER_TOKEN on 401, wait Retry-After on 429) and retries the server, so fixing the environment needs no restart. Prefer the hosted endpoint directly wherever your client supports remote MCP servers.

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "voyagier": { "command": "npx", "args": ["-y", "@voyagier/cli", "mcp"], "env": { "VOYAGIER_TOKEN": "voy_pat_xxxxx" } } } }

Environment Variables

| VOYAGIER_CONFIG_DIR | Directory for t