Deployment

Configuration is a directory of files. Deploying zips it and uploads it; the platform diffs it against the workspace and applies the difference.

The loop

polymesa retrieve ./config     # pull current state
# edit, commit
polymesa deploy ./config --dry-run
polymesa deploy ./config

What moves

Folder	Contents
`groups/`	Groups and hierarchy
`entities/`	Entity and field definitions
`guest_files/`	Triggers, jobs, controllers, views
`automations/`	Automation definitions
`share_rules/`	Model-level sharing rules
`email_senders/`	Sender addresses

Plus pages/_meta.json when custom pages exist.

Records never move with a deploy. Neither do user accounts or manual record shares.

Dry runs

polymesa deploy ./config --dry-run

Validates and reports per-folder change counts without committing. Make it a required step in CI — it is the only place an unintended delete is visible before it happens.

Promoting between environments

Aliases make this mechanical: retrieve from one, deploy to another.

polymesa retrieve ./config --alias staging
polymesa deploy   ./config --alias prod --dry-run
polymesa deploy   ./config --alias prod

Since users are not configuration, promoting never disturbs accounts in the target.

CI

Use a connected app rather than a password, and environment variables rather than flags:

export POLYMESA_API_URL=https://api.polymesa.com
export POLYMESA_TOKEN="$(cat token.txt)"

polymesa deploy ./config --dry-run
polymesa deploy ./config

Pin the CLI version in CI so a release cannot change deploy behavior underneath you:

curl -fsSLO https://dl.polymesa.com/cli/1.0.0/polymesa-x86_64-unknown-linux-gnu

Seeding data

Data is a separate step, on purpose:

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

upsert never deletes. To remove records, use delete with an explicit CSV of keys — and note it has no dry run.