> ## Documentation Index
> Fetch the complete documentation index at: https://voyant.travel/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI overview

> One command-line tool for the open-source platform and Voyant. Scaffold, generate, run scripts, and manage cloud resources.

The Voyant CLI is a single binary that drives both the open-source platform and Voyant. The open-source commands need no login and work against any Voyant project. The cloud commands need a Voyant token.

## Install

```bash theme={null}
npm install -g @voyant-travel/cli
```

You can also use `pnpm add -g @voyant-travel/cli`. Check it works:

```bash theme={null}
voyant --help
voyant --version
```

## Two modes

**Open source, no login required.** Scaffolding, code generation, config inspection, database tooling, and a TypeScript script runner. These work standalone.

```bash theme={null}
voyant new my-app --template operator
voyant generate module invoices
voyant config show
voyant db generate
voyant exec ./scripts/backfill.ts
```

**Cloud, needs a token.** Authenticate once, then drive the whole platform from your terminal — apps, environments, deployments, runtime logs, databases, storage, and vault.

```bash theme={null}
voyant login
voyant whoami
voyant apps list
voyant env set my-app STRIPE_KEY sk_live_xyz --secret
voyant deploy my-app
voyant logs my-app --level error --since 1h
voyant databases list
```

See the [command reference](/docs/cli/commands) for the full list.

## Built for agents

Every cloud command takes `--json` for machine-readable output and returns a stable `{ "error": { "code", "message" } }` envelope on failure. Destructive actions require `--yes`, and nothing prompts when there is no TTY — so an agent (or a CI job) can drive the entire control plane unattended.

```bash theme={null}
voyant apps list --json
voyant deploy my-app --json
voyant databases connection db_123 --json
```

## Logging in

`voyant login` runs an OAuth 2.0 device-code flow ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) against `https://api.voyant.travel/cli/v1/device/*`. It prints a verification URL, opens it in your browser, and polls until you approve. Suppress the browser with `--no-browser`.

For CI or headless use, mint an API token in the dashboard tokens UI and paste it:

```bash theme={null}
voyant login --token tok_live_xyz
```

## Organizations

API tokens are organization-bound, so each organization you log in to is stored as its own token. When you belong to several, pick which one commands target:

```bash theme={null}
voyant org list          # orgs you're logged in to (active one is marked)
voyant org use acme      # switch the active org
voyant org current       # show the active org
```

Override per command with `--org <slug|id>` or the `VOYANT_CLOUD_ORG` environment variable. If several orgs are logged in and none is selected, commands fail with a clear message rather than guessing.

## Where credentials live

The minted token is stored in `~/.voyant/credentials.json` (mode 0600), keyed by API URL **and organization** — so you can be logged into multiple environments (production, staging, a self-hosted instance) and multiple organizations at once.

On every cloud command, the token is resolved in this order:

1. A `--token <value>` flag.
2. The `VOYANT_CLOUD_API_KEY` environment variable.
3. The stored credential for the resolved API URL and active organization.

The active organization is chosen by `--org` → `VOYANT_CLOUD_ORG` → the org set with `voyant org use` → the sole logged-in org.

## A typical flow

```bash theme={null}
voyant new my-travel-app --template operator   # scaffold
cd my-travel-app && pnpm install
voyant generate module loyalty                 # add a module
voyant generate extension booking-notes --module bookings  # extend a module
voyant db generate && voyant db migrate         # schema
voyant login                                     # authenticate to cloud
voyant secrets set production STRIPE_KEY sk_live_xyz
```

## Next steps

<Card title="Command reference" icon="terminal" href="/docs/cli/commands">
  Every command, subcommand, and flag.
</Card>