Command reference

polymesa <command> [options]

Command	What it does
`login`	Authenticate with email and password, print a JWT
`auth`	Manage stored credentials
`retrieve`	Download configuration to a local directory
`deploy`	Upload a configuration directory
`upsert`	Insert or update records from CSV
`delete`	Delete records listed in a CSV
`query`	Run a SQL SELECT and export CSV
`pages`	Deploy or retrieve custom pages
`types`	Generate local TypeScript definitions

Common flags

Every command that talks to the API accepts these:

Flag	Default	Purpose
`-u, --url <url>`	`$POLYMESA_API_URL`, else `http://localhost:3000`	API base URL
`-a, --alias <alias>`	`default`	Which stored credentials to use
`-t, --token <token>`	`$POLYMESA_TOKEN`	Bearer token, overriding stored credentials
`--workspace <slug>`	the alias’s default	Act in this workspace

Authenticate and print a JWT to stdout. Does not store anything — see auth login for that.

polymesa login --email <email> --password <password>

Flag	Required	Purpose
`-e, --email <email>`	yes	Email address
`-p, --password <password>`	yes	Password
`-u, --url <url>`	no	API base URL

auth

Credential management. See Authentication for the flows.

polymesa auth login [--alias <alias>] [--jwt --client-id <id> --key-file <path> --username <user>]

Flag	Purpose
`-a, --alias <alias>`	Store under this name (default `default`)
`--jwt`	Use the JWT bearer flow instead of the browser flow
`--client-id <id>`	Connected app client ID (JWT flow)
`--key-file <path>`	RSA private key path (JWT flow)
`--username <user>`	Username for the `sub` claim (JWT flow)

With no --jwt, opens a browser for OAuth.

auth logout

polymesa auth logout [--alias <alias>] [--all]

auth list

Lists stored credentials. polymesa auth ls also works.

auth whoami

Shows the currently authenticated user.

polymesa auth whoami [--alias <alias>] [--workspace <slug>]

retrieve

Downloads the current configuration into a directory, as editable files you can commit to version control.

polymesa retrieve [dir]
polymesa retrieve --directory ./config

Flag	Purpose
`-D, --directory <dir>`	Output directory, if you prefer a flag to the positional argument

Writes the configuration folders, plus pages/_meta.json when the workspace has custom pages.

deploy

Zips a configuration directory and uploads it.

polymesa deploy [dir]
polymesa deploy ./config --dry-run

Flag	Purpose
`-d, --dry-run`	Validate and report what would change, without committing
`-D, --directory <dir>`	Project directory, as an alternative to the positional argument

Configuration bundle

retrieve and deploy move these folders:

Folder	Contents
`groups/`	User groups and their hierarchy
`entities/`	Entity definitions — your tables and fields
`guest_files/`	TypeScript you author: triggers, jobs, controllers, views
`automations/`	Automation definitions
`share_rules/`	Model-level sharing rules
`email_senders/`	Configured sender addresses

upsert

Inserts or updates records from a CSV. Matches on primary key: present rows are updated, absent ones inserted. Never deletes.

polymesa upsert --entity Issue --file ./issues.csv

Flag	Required	Purpose
`-e, --entity <entity>`	yes	Entity to upsert into
`-f, --file <file>`	yes	Path to the CSV

The CSV’s header row must match field names. To seed user accounts, target the __user entity; its groups column takes a ;-separated list.

polymesa upsert --entity __user --file ./users.csv

delete

Deletes records whose primary key appears in the CSV.

polymesa delete <entity> <csv-file>
polymesa delete Issue ./stale-issues.csv

Only the primary key column is read; everything else is ignored, so you can pass a filtered export of a previous query straight back in.

query

Runs a SQL SELECT and writes the result as CSV.

polymesa query --sql "SELECT * FROM issue WHERE status = 'new'"
polymesa query --sql "SELECT * FROM issue" --output issues.csv

Flag	Required	Purpose
`-s, --sql <query>`	yes	The SELECT statement
`-o, --output <file>`	no	Write here instead of stdout

Runs as your user, so row-level sharing rules apply — results are limited to records you can see.

pages

Manage custom pages independently of a full config deploy.

polymesa pages deploy <dir> [--dry-run]
polymesa pages retrieve <dir>

Both read and write pages/_meta.json inside the given directory. A full deploy already includes pages when that file is present; these subcommands are for iterating on pages alone.

types

Generates TypeScript definitions for system types and your entities, so editors can autocomplete against your actual schema.

polymesa types [dir]
polymesa types --directory ./my-workspace

Writes into .polymesa/ inside the target directory. Re-run it after changing entities. See Entities for what gets generated.