# CLI reference

Source: https://cloud.synteq.com/docs/cli-reference
Updated: 2026-10-18T03:08:16.557665+00:00

---
# CLI reference

Every `synteq` command, grouped as in `synteq --help`. `synteq help <command>` prints current help and examples. For installation, see Getting started with the CLI.

## Conventions

- `synteq <group> <command>`; `synteq app:logs` also works and is the form errors use.
- Bare `synteq` on a terminal opens the TUI (`synteq tui`). `synteq <group>` alone usually lists.
- Destructive commands confirm on a terminal. When piped, pass `--yes` (`-y`) or the command exits 1 without acting.
- Under an API key, `--help` hides commands the key can't run.

## Global flags and environment

| Flag | Description |
| --- | --- |
| `-o table`, `-o json` | Output format. Default: table on a terminal, JSON when piped. |
| `--help` | Show help for the command. |

| Variable | Description |
| --- | --- |
| `SYNTEQ_API_TOKEN` | API key for the current shell. Overrides stored credentials. |
| `SYNTEQ_PROFILE` | Connection profile to use instead of the active one. |
| `SYNTEQ_API_BASE_URL` | API base URL. Overrides the profile and the stored URL. |
| `SYNTEQ_NO_KEYCHAIN=1` | Store credentials in a file instead of the OS keychain. |
| `SYNTEQ_TUI` | Render mode for one-shot commands: `on`, `off`, or `auto`. |
| `NO_COLOR` | Disable colour output. |
| `XDG_CONFIG_HOME` | Config directory base (default `~/.config`). |

| File | Description |
| --- | --- |
| `~/.config/synteq/config.json` | API URL, active team and project, profiles, directory links, render mode. |
| `~/.config/synteq/tokens.json` | Stored login when no keychain is available. Named profiles use `tokens-<profile>.json`. |
| `~/.config/synteq/min-version.json` | Cached minimum-version check, refreshed every six hours. |

On Windows the directory is `%APPDATA%\synteq`.

## Auth and identity

Every command works with a browser session. An API key runs only the commands whose scope it holds; the scope is listed in the server, storage, and billing tables below. Everything else (`whoami`, account, team, config, Apps, Functions, SSH keys, tickets, the TUI) is session-only. `login`, `logout`, and `autocomplete` always run.

| Command | Description |
| --- | --- |
| `synteq login` | Sign in through the browser. `--with-token` reads an API key (`sk_…`) from stdin and stores it; prompts with masked input on a terminal. |
| `synteq logout` | Revoke the session and clear stored credentials. If the portal is unreachable, local credentials are still cleared. |
| `synteq whoami` | Signed-in account and auth mode. `--full` returns the raw account payload. |
| `synteq account` | Account details. Same as `synteq account show`. |

## Team, project, and config

| Command | Description |
| --- | --- |
| `synteq team [query]` | Show the active team, or switch by name substring or id prefix. `--list` lists all, `--pick` opens a picker. |
| `synteq team details` | Org and billing details. `--team-id` picks the team. |
| `synteq projects` | Projects in the active team. Same as `projects list`. |
| `synteq config` | Active profile, team, project, and user. Same as `config show`; `--verbose` adds the API URL and file paths. |
| `synteq config profile list` | Saved connection profiles. |
| `synteq config profile add <name> <url>` | Create or update a profile: a named API URL with its own login. |
| `synteq config profile use <name>` | Switch profile. `default` clears it. |
| `synteq config profile remove <name>` | Delete a profile and its login. Alias `rm`. |
| `synteq settings` | Active team, project, user, API URL, and render mode. |

## Apps

App commands take `--app <slug or uuid>`. Without it, the CLI uses the app linked to the current directory or its nearest linked parent.

### Create and link

| Command | Description |
| --- | --- |
| `synteq apps list` | Apps in the active project. `--project <id>` |
| `synteq apps create --slug <slug>` | Create an app. `--plan` (default `starter`), `--region` (default `us-central`), `--project` |
| `synteq link` | Link the directory to an app through a walkthrough: team, project, pick or create an app, optional env vars, optional GitHub. |
| `synteq status` | Linked app, status, hostname, plan, release, and last build. |
| `synteq app unlink` | Remove the directory's link. |

| Flag on `link` | Description |
| --- | --- |
| `--app <slug>` | Link to this app and skip the walkthrough. |
| `--project <id>` | Project to use. |
| `--remove` | Remove the link. |
| `--no-interactive` | Never prompt. Requires `--app`. |

### Deploy

`synteq deploy` builds and ships the current directory, or rolls out an image.

| Flag | Description |
| --- | --- |
| `--app <slug>` | Target app. Default: the linked app. |
| `--dir <path>` | Directory to pack and upload (default `.`). Excludes `.git`, `node_modules`, `.venv`, `__pycache__`. Build output such as `dist` is kept. |
| `--image <ref>` | Deploy an existing registry image. Can't be combined with `--dir`. |
| `--no-wait` | Return once the build is queued. |
| `--poll-interval <s>` | Seconds between polls (default 5, minimum 2). |
| `--timeout <s>` | Stop waiting after this many seconds (default 900). The build continues server-side. |

In an unlinked directory on a terminal, `synteq deploy` runs the `link` walkthrough and stops before building.

### Deployments

| Command | Description |
| --- | --- |
| `synteq app deployment list` | Releases, newest first. |
| `synteq app deployment show <ref>` | One build or release: status, steps, trigger. `<ref>` is a build id, release id, or release number such as `9`. |
| `synteq app deployment rollback --to <n>` | Redeploy release `n`'s image as a new release. `--yes` |

### Environment variables

`synteq env` is the short form of `synteq app env`.

| Command | Description |
| --- | --- |
| `synteq env list`, `synteq app env list` | Keys and scope. Values are never listed. |
| `synteq env set KEY=VALUE`, `synteq app env add KEY=VALUE` | Set a variable, stored as a secret. Quote the pair if the value has spaces. `--scope runtime|build|both` (default `runtime`), `--note <text>` (up to 500 chars). |
| `synteq app env reveal KEY` | Show one value. Config values print in full; secrets are masked to their tail. |
| `synteq app env rm KEY` | Delete a variable. `--yes` |

### Build and deploy settings

`synteq app settings show` prints current values. `synteq app settings set` changes only the flags passed.

| Flag on `settings set` | Description |
| --- | --- |
| `--root-directory <dir>` | Subdirectory to build from. |
| `--dockerfile-path <path>` | Dockerfile path, relative to the build context. |
| `--build-context <dir>` | Docker build context. |
| `--docker-command <cmd>` | Container start command override. |
| `--pre-deploy-command <cmd>` | Runs once before each deploy, for example migrations. |
| `--auto-deploy on_commit|off` | Deploy on every push, or manually only. |
| `--health-check-path <path>` | HTTP path that must pass before a deploy is healthy, for example `/healthz`. |
| `--port <n>` | Port the app listens on. `0` clears it and lets the runtime detect the port. |

### Domains

| Command | Description |
| --- | --- |
| `synteq app domain list` | Default and custom domains with TLS status. |
| `synteq app domain add <hostname>` | Attach a domain and print the DNS records to create. `--accept-fee` for the first custom domain on a plan that charges for it. |
| `synteq app domain verify <domain-id>` | Re-check DNS and TLS. |
| `synteq app domain remove <domain-id>` | Detach a domain. `--yes` |

TLS states are described in Deploying and configuring an app.

### Plans

| Command | Description |
| --- | --- |
| `synteq app plan show` | Current plan and available plans. |
| `synteq app plan change <tier>` | Change plan after a proration preview. Tiers: `free`, `hobby`, `starter`, `pro`. `--at now|cycle_end` (default `now`), `--yes` |

### Logs, metrics, and health

| Command | Description |
| --- | --- |
| `synteq logs [app]` | Stream live container logs until Ctrl-C. `--no-follow` prints buffered lines and exits. |
| `synteq app logs` | Search log history. `--since 15m`…`4320h` (default `1h`), `--from`/`--until` (ISO instant or age like `2h`), `--search <text>`, `--container <name>`, `--limit` 1–5000 (default 500). |
| `synteq app metrics` | CPU, memory, and network against the plan, with peak and average. `--range 15m|1h|6h|24h|72h|168h` (default `1h`) or `--from`/`--until`. `-o json` returns the raw series. |
| `synteq app health` | Probe the app's health endpoint through the cluster. |

Timestamps print in your local time zone. `-o json` returns ISO instants.

## Functions

Function commands take a positional name or `--name <slug or uuid>`. Without either, the CLI uses the function linked by `synteq function init`. A directory linked to an app can't be used for function commands, and vice versa.

### Create and deploy

| Command | Description |
| --- | --- |
| `synteq function init [name]` | Create or reuse a function, link the directory, and write a starter handler if there's no entry file or Dockerfile. Safe to re-run. `--runtime node22|python312`, `--plan`, `--location <code>` (e.g. `dfw`), `--dir`, `--no-scaffold`, `--project` |
| `synteq function create <name>` | Create without linking. Hostname: `<name>.fn.synteq.app`. `--runtime` (default `node22`), `--plan`, `--region` or `--location`, `--project` |
| `synteq function list` | Functions in the active project. `--project` |
| `synteq function show [name]` | Configuration, current release, and health. |
| `synteq function deploy` | Upload the directory's text files and follow the build and release. `--dir`, `--no-wait`, `--poll-interval` (default 3, minimum 2), `--timeout` (default 600), `--yes` skips the runtime-mismatch confirmation. |
| `synteq function unlink` | Remove the directory's link. |
| `synteq function delete [name]` | Delete the function and its directory link. `--yes` skips the type-the-slug confirmation. |

`function deploy` uploads:

- Text files only. A file with a NUL byte in its first 8 KiB is skipped as binary.
- Everything except, at any depth: `node_modules`, `.git`, `.synteq`, `__pycache__`, `.venv`, `venv`, `dist`, `build`, `target`, `.DS_Store`, `*.log`, and paths matched by `.synteqignore` (gitignore syntax) in the deploy directory.
- Up to 32 files, about 900 KB total, 512 KiB per file. Over the total, the CLI names the largest files and stops.

Entry files, checked in order:

| Runtime | Entry files |
| --- | --- |
| `node22` | `index.mjs`, `index.js`, `handler.mjs`, `handler.js`, `main.mjs`, `main.js` |
| `python312` | `handler.py`, `main.py`, `index.py`, `app.py` |

A directory with a Dockerfile builds as a container and ignores the runtime setting. The handler contract is in Writing and deploying a function.

### Releases, invocation, and logs

| Command | Description |
| --- | --- |
| `synteq function releases [name]` | Releases, newest first, current one marked. |
| `synteq function rollback --to <n>` | New release from release `n`'s image. `--yes` |
| `synteq function invoke [name]` | Plain HTTPS request to the function's hostname, no Synteq credentials attached. `--path` (default `/`), `--method` (default `GET`), `--data`/`-d`, `--content-type` (default `application/json`), `--header KEY:VALUE` (repeatable). `-o json` returns `{status, ms, headers, body}`. |
| `synteq function logs [name]` | Recent invocations, newest first. `--limit` (default 20, max 100), `--status success|failed|timeout`, `--release <n>`, `--search <text>`, `--lines` adds captured output, `--follow`/`-f` polls every 3 seconds. |

### Environment variables

| Command | Description |
| --- | --- |
| `synteq function env list` | Keys, kind, and scope. Never values. |
| `synteq function env set KEY=VALUE` | Set a variable. `--kind secret|config` (default `secret`), `--scope` (default `runtime`), `--note` |
| `synteq function env reveal KEY` | One value. Secrets are masked to the last 4 characters; config prints in full. |
| `synteq function env rm KEY` | Delete a variable. `--yes` |

### Cron triggers

Schedules are five-field cron expressions in UTC. Each firing is a normal invocation: metered, logged, and listed by `function logs`. Trigger ids are the short ids from `cron list` or the full UUID.

| Command | Description |
| --- | --- |
| `synteq function cron list` | Triggers on the function. |
| `synteq function cron add "<schedule>"` | Add a trigger. Quote the schedule. `--description`/`-d`, `--retries 0..2`, `--disabled` |
| `synteq function cron update <id>` | Change only the flags passed. `--schedule`/`-s`, `--description`, `--retries`, `--enable`, `--disable` |
| `synteq function cron rm <id>` | Delete a trigger. To pause, use `update --disable`. `--yes` |
| `synteq function cron run <id>` | Fire now, outside the schedule. |

## Servers

`vps`, `vds`, `gpu`, and `instant-metal` share one command set. Replace `vps` with the group name.

| Command | Description | API-key scope |
| --- | --- | --- |
| `synteq vps list` | List instances. Same as bare `synteq vps`. | `read:vps` |
| `synteq vps details [id]` | Full details. Without an id, pick from a list. | `read:vps` |
| `synteq vps order` | Order an instance. Interactive on a terminal, flag-driven when piped. | `write:orders` |
| `synteq vps power <on|off|reboot|shutdown|cycle>` | Power actions. All but `on` confirm on a terminal. | `write:vps:power` |
| `synteq vps reinstall` | Reinstall with a new OS image. Erases all data. | `write:vps:reinstall` |
| `synteq vps resize` | Change CPU, RAM, disk, or bandwidth in place after a prorated quote. | `write:resize` |
| `synteq vps console` | Serial console, or a browser URL for graphical. | session |
| `synteq vps stats` | Live CPU, memory, disk, uptime, and network I/O. | `read:vps` |
| `synteq vps bandwidth` | Month-to-date usage, allowance, overage, up to 12 months of history. | `read:vps` |
| `synteq vps activity` | Recent activity log. | session |
| `synteq vps boot-order` | View or set boot order. | `write:vps:settings` |
| `synteq vps ip list` | IP addresses and extra-IP add-ons. | `read:vps` |
| `synteq vps ip add` | Buy extra IPv4 addresses. Charges immediately. | session |

Scopes for the other groups replace `vps` with `vds`, `gpu_cloud`, or `instant_metal`.

`synteq baremetal` (scopes `read:baremetal`, `write:baremetal:power`) has `list`, `details`, `order`, `power`, `reinstall`, `install-password` (one-time install password, available for 7 days after provisioning), `console` (BMC console through the portal), `bandwidth`, and `activity`. Bare metal has no serial console.

## Storage, ordering, and catalog

| Command | Description | API-key scope |
| --- | --- | --- |
| `synteq storage list` | Block storage volumes. | `read:storage` |
| `synteq storage order` | Order a volume. Same as `synteq order storage`. | `write:orders` |
| `synteq storage attach` | Attach a detached volume to a server in the same cluster. | `write:storage` |
| `synteq storage detach` | Detach a volume. Confirms on a terminal. | `write:storage` |
| `synteq storage resize` | Grow a volume. Volumes can't shrink. | `write:resize` |
| `synteq order` | Picker for what to order. Subcommands: `vps`, `gpu`, `instant-metal`, `storage`. | `write:orders` |
| `synteq catalog` | Products and plans. | `read:orders` |
| `synteq os-images` | OS images for orders and reinstalls. | `read:orders` |
| `synteq resources` | All resources across kinds. | session |
| `synteq transit` | IP transit services. | `read:transit` |

## Billing, SSH keys, and tickets

| Command | Description | Auth |
| --- | --- | --- |
| `synteq credits` | Credit balance and recent history. Same as `credits list`. | `read:billing` |
| `synteq credits add` | Buy credit with a saved payment method. Interactive on a terminal. | session |
| `synteq payments` | Saved payment methods. Same as `payments methods list`. | session |
| `synteq payments methods add` | Open the portal to add a method. | session |
| `synteq payments methods set-default <id>` | Set the team default. | session |
| `synteq payments methods delete <id>` | Remove a method. `--yes` when piped. | session |
| `synteq ssh-key list`, `add`, `delete` | SSH public keys on your account. | session |
| `synteq tickets list`, `open`, `create`, `reply`, `close`, `reopen`, `download`, `departments` | Support tickets. Alias `synteq ticket`. | session |

## The api escape hatch

`synteq api` sends an authenticated request as you to any portal API path and prints the raw JSON. Prefer a dedicated command where one exists; those validate input and format output. Paths are listed in the API reference at cloud.synteq.com/docs/api.

```
synteq api GET /orders/catalog --query category=gpu_cloud
synteq api POST /orders/preview --input body.json

```

| Argument or flag | Description |
| --- | --- |
| `<method>` | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. |
| `<path>` | API path starting with `/`. Full URLs are refused. |
| `--input <file>` | JSON body from a file, or `-` for stdin. Piped stdin is used automatically. |
| `--query key=value` | Query parameter. Repeatable. |
| `--header key:value` | Extra header. Repeatable. `Authorization` and `X-API-Key` can't be overridden. |
| `--include` | Print response status and headers to stderr before the body. |

Output is pretty-printed on a terminal and compact when piped.

## Exit codes and errors

| Code | Meaning |
| --- | --- |
| 0 | Success. |
| 1 | User error: bad flags, unknown slug, missing scope, refused confirmation. |
| 2 | Not signed in, or the session expired. Run `synteq login`. |
| 3 | Server error (5xx), or the portal is unreachable. |
| 4 | CLI older than the portal's minimum version. Run `npm install -g synteq@latest`. |

In JSON mode, errors go to stderr as one object. Include the `request_id` when contacting support.

```
{"error":{"detail":"...","status":404,"request_id":"...","exit_code":1}}

```

The minimum-version check uses a cache refreshed every six hours and passes if the portal is unreachable. `login`, `logout`, and `settings` are exempt.

## Scripting and CI

- Apps and Functions need a session. A deploying CI job must reuse a session stored by `synteq login` on a machine where the browser flow was completed.
- `--no-wait` on `deploy` and `function deploy` returns the build row at once. Poll with `synteq app deployment show <id>` or `synteq function releases`.
- `synteq status -o json` returns `{ link, app, lastBuild }`.
- `SYNTEQ_PROFILE` selects a connection profile per job.