CLI

Installation

Choose an installation method below that best fits your project or system requirements.

cURL

Linux

curl -fsSL https://cli.platter.dev/linux | sh

macOS

curl -fsSL https://cli.platter.dev/macos | sh

Windows

Run cmd.exe as an administrator, then:

curl https://cli.platter.dev/windows | cmd

After installation, make sure that %ProgramFiles%\platter is included in your %PATH% for ease-of-use.

Node

npm

npm install -D platter

yarn

yarn add -D platter

Installing platter globally (i.e. with the --global flag) through npm is not recommended. For Node projects, it's best to pin the platter CLI version to a project and use npx to invoke platter, e.g.:

npx platter postgres create

If you would like to use platter outside of a Node project, use one of the cURL installation methods.

Resource Commands

All resources (e.g. postgres) have their own set of common subcommands available. To see which subcommands are available, you can always use platter <resource> --help.

Platter resources expose the same top-level commands, which can be invoked with platter <resource> <command>, e.g. platter postgres create. Supported commands:

create

Creates a new instance of a resource along with a trunk branch. When --clients are included, client configurations are added to the configuration file and generated in configured target directories.

USAGE:

platter <resource> create [FLAGS] [OPTIONS] [--] [name]

ARGS:

<name> name of the instance to create

FLAGS:

-B, --no-auto-branch disable auto-branching in configuration

OPTIONS:

-c, --client <client>... clients to generate after instance creation [aliases: platform]

[short aliases: p]

-d, --directory <directory> target directory for generated clients

-f, --file <file>... files to inject branch urls into after instance creation

-t, --trunk <trunk> trunk branch for the new instance

list

Lists active resource instances.

USAGE:

platter <resource> list [OPTIONS]

OPTIONS:

-o, --output <output> output format of the list [default: table] [possible values: Json, Ndjson, Table, Text]

delete

Deletes a single resource instance by name.

USAGE:

platter <resource> delete [name]

ARGS:

<name> name of the instance to delete

Branch Commands

Branches of a resource can also be managed through a branch subcommand, e.g. platter postgres branch create. Supported commands:

create

Creates a new branch of an existing instance of a resource.

USAGE:

platter <resource> branch create [OPTIONS] [name]

ARGS:

<name> name of the branch to create

OPTIONS:

-i, --instance <instance> name or ID of the database instance you would like to branch

-p, --parent <parent> name of the parent branch of your new branch

list

Lists active branches, grouped by resource instance.

USAGE:

platter <resource> branch list [OPTIONS]

OPTIONS:

-i, --instance <instance> name or ID of a database instance you would like filter branches by

-o, --output <output> output format of the list [default: table] [possible values: Json, Ndjson, Table,

Text]

delete

Deletes a single branch.

USAGE:

platter <resource> branch delete [OPTIONS] [name]

OPTIONS:

-i, --instance <instance> name or ID of the branch's instance

ARGS:

<name> name of the branch to delete

url

If a resource branch can be accessed directly without a client, then url returns the stable URL for direct access. URLs are resource-specific, e.g. Postgres URLs are in standard Connection URI format of postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&...]

USAGE:

platter <resource> branch url [OPTIONS] [name]

OPTIONS:

-i, --instance <instance> name or ID of the branch's instance

ARGS:

<name> name of the branch to delete

Client Commands

Some instances are connected to specific projects. The client subcommands allows for different connection methods within a single project by handling configuration and client generation separately from instance creation.

Most clients will be created through the --client flags in the create command, but these commands exist separately where needed.

configure

Adds configuration for a single client to the configuration file.

USAGE:

platter <resource> client configure [FLAGS] [OPTIONS] [platform]

ARGS:

<platform> target platform of the client [possible values: node, web]

FLAGS:

-B, --no-auto-branch disable auto-branching in client configuration

OPTIONS:

-d, --directory <directory> target directory for the generated client

-i, --instance <instance> name or ID of the client's target database instance

generate

Generates clients that have been previously created and configured. This command accepts instance and directory filters for generating specific clients.

USAGE:

platter <resource> client generate [OPTIONS] [platform]

ARGS:

<platform> target platform to generate clients for [possible values: node, web]

OPTIONS:

-d, --directory <directory> target directory to generate clients for

-i, --instance <instance> name or ID of the database instance to generate clients for

File Commands

Some instances are connected to specific non-JavaScript projects that require more flexibility than the built-in Node and Web clients allow. The file subcommands allows for different connection methods within a single project by injecting branch URLs into configuration files. These command support either JSON or .env/dotenv-style configuration files.

Most files will be created through the --file flags in the create command, but these commands exist separately where needed.

configure

Adds configuration for a single file to the configuration.

USAGE:

platter <resource> file configure [FLAGS] [OPTIONS] [format]

ARGS:

<format> format of the target file [possible values: json, env]

FLAGS:

-B, --no-auto-branch disable auto-branching in configuration

OPTIONS:

-f, --file <file> path to the file used for variable injection

-i, --instance <instance> name or ID of the watched branch's target instance

-k, --key <key> key to use when injecting branch URIs into the configuration file

generate

Generates files that have been previously created and configured. This command accepts instance, key, and file filters for generating specific files.

USAGE:

platter <resource> file generate [OPTIONS] [format]

ARGS:

<format> format of files to generate [possible values: json, env]

OPTIONS:

-f, --file <file> path to the file to generate

-i, --instance <instance> name or ID of the database instance to generate files for

-k, --key <key> key to generate

Development Commands

In addition to resource management commands, the following commands are provided to help with generating clients in git repositories with a platter configuration entry in package.json.

build

Builds new clients for a branch using the current active git branch, falling back to git's init.defaultbranch configuration or to main. Will fail if the branch does not already exist.

USAGE:

platter <resource> build [OPTIONS]

OPTIONS:

-i, --instance <instance> resource instance name or ID to rebuild

If <resource> is omitted (i.e. platter build), all configured clients across all resources are built.

watch

Runs branch create and build for each resource in the configuration file using the previous git branch as the parent of new branches and the current git branch as the name of new branches. The process is repeated every time the git branch changes, making sure that your local clients, remote branches, and version control never get out of sync while building new features. For more information on the watch command and auto-branching, see Branching.

USAGE:

platter watch [OPTIONS]

OPTIONS:

-i, --instance <instance> instance name or ID to watch

Special Commands

identity is a special resource that only contains a login command for logging in as a specific user. You should only need to use this command to change active users.