@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 <tool_name> --<param> <value> — 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 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@<version>.

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 "[email protected]" --json

# 2) Resolve the destination, then scaffold the plan with its party
voyagier search_destinations --query "Lisbon" --json
voyagier create_plan --client_id <CLIENT_ID> --title "Doe — Lisbon" \
  --travel_destination_id <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 <SEARCH_ID>
voyagier promote_search --plan_id <PLAN_ID> --search_id <SEARCH_ID> --goal_id <GOAL_ID> --json

# 4) Options → pick
voyagier get_options --selection_id <SELECTION_ID>
voyagier select_option --option_id <OPTION_ID> --json

# 5) Readiness, quote, book at exactly the quoted price
voyagier get_plan_status --plan_id <PLAN_ID>
voyagier get_plan_quote --plan_id <PLAN_ID>
voyagier book_plan --plan_id <PLAN_ID> --expect_total_cents <CENTS> --item_ids <ID> <ID> --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 <tool_name> --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 <id> --cover_media_id null clears the cover photo. Every repeatable array flag has a --no-<flag> 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 <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, API_ERROR (the tool's own error text), NETWORK, COMMAND_REMOVED.
• Tool cache. The server's tool list is cached in ~/.voyagier/tools-cache.json for 24 hours. voyagier doctor refreshes it, and so does running a tool name the cache does not know yet. 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

| Command | Description | |---------|-------------| | voyagier <tool_name> | One command per MCP tool, for example list_plans, search_destinations, create_plan, search_flights, promote_search, get_options, select_option, get_plan_status, get_plan_quote, book_plan. voyagier --help lists the server's current set; search_tools and get_tool_details find and describe tools from inside the CLI | | voyagier doctor | Self-check: credentials, MCP server connection + tool list, identity, state, version | | voyagier auth | Manage the Personal Access Token (login, set-token, status, logout, setup) | | voyagier mcp install <client> | Point an MCP client (Claude Code, Cursor, Claude Desktop) at the Voyagier MCP server | | voyagier mcp | Run a stdio MCP server that proxies the hosted Voyagier MCP server | | voyagier agent-docs | Print the server's agent guidance, then the CLI usage notes (AGENT.md) | | voyagier telemetry | Anonymous usage telemetry (status, on, off) |

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 <client> 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 <pat> 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

| Variable | Description | |----------|-------------| | VOYAGIER_TOKEN | Personal access token (overrides the saved one) | | VOYAGIER_MCP_URL | MCP endpoint every tool command, the stdio proxy and the extension call (default: https://mcp.voyagier.com/api/mcp). Must be https://; plain http:// is accepted only for localhost / 127.0.0.1 / ::1 during local development | | VOYAGIER_API_URL | GraphQL base URL used by voyagier auth setup profile updates (default: https://travel.voyagier.com/api); honored together with VOYAGIER_TOKEN | | VOYAGIER_CONFIG_DIR | Directory for credentials and the tool cache (default: ~/.voyagier) |

How It Works

The CLI is an MCP client. On startup it loads the server's tools/list (from the local cache when fresh) and registers one Commander command per tool, with flags generated from each tool's JSON input schema. Running a command sends tools/call over Streamable HTTP with your token as a Bearer header, honours the server's session and rate-limit headers, and prints the result. The order of operations, how searches complete and how booking is gated are the server's rules; read them with voyagier agent-docs and in each tool's --help.

Rate limit. The hosted endpoint allows 180 requests per minute per token, counted across the CLI, the stdio proxy and any other client using that token. Scripted loops should back off; the CLI reports RATE_LIMITED with details.retryAfterSeconds when the server sends Retry-After.

Getting Access

Voyagier access is granted, not open signup — request access at voyagier.com/agents. That's the gate for advisors, trip-planner customers, and agent builders alike.

Once your account is granted API access, mint a personal access token at travel.voyagier.com/me/settings/tokens and you're in. Two account tiers use the CLI today:

• Travel advisors — manage a book of clients (list_clients, create_client); plans are created against a client (create_plan --client_id <CLIENT_ID>).
• Trip planners — customers planning their own travel. Omit --client_id: create_plan puts the plan on your own client record (the isSelf: true entry list_clients returns) automatically.

Non-admin tokens expire (90 days max, 30 by default) — mint a fresh one when yours lapses.

Tip: prefer voyagier login (interactive prompt) over voyagier auth set-token <token> — it keeps your token out of shell history. For scripts, pipe the token via stdin (echo "$VOYAGIER_PAT" | voyagier auth set-token -) or use the VOYAGIER_TOKEN env var.

Claude Desktop Extension (MCPB)

The stdio proxy is also packaged as a Claude Desktop extension bundle (MCPB): the extension connects Claude Desktop to the hosted Voyagier MCP server with the Personal Access Token you enter when installing it, and always exposes the server's current tools. Build it from the repo with scripts/build-mcpb.sh, which produces dist-mcpb/voyagier-<version>.mcpb. To install, drag the .mcpb file into Claude Desktop → Settings → Extensions, then enter your token when prompted.

Privacy Policy

Data processed through the CLI and Voyagier services is handled per the Voyagier privacy policy.

License

Apache-2.0 — Copyright 2026 Voyagier, Inc. Use of Voyagier services through the CLI is subject to the Voyagier Terms of Service. "Voyagier" and the Voyagier logo are trademarks of Voyagier, Inc.; the Apache-2.0 license does not grant trademark rights.