Manage PloyDB with the CLI

Create and manage databases, tables, columns, and rows from the command line. You can also duplicate data asynchronously and import typed CSV files.

Databases

`ploy database list [--json]`

Lists the current workspace's databases.

ploy database list
ploy database list --json

--json prints { "databases": [...] } instead of tab-separated database ID and name lines.

`ploy database create --name <name> [options]`

Creates an empty database, or asynchronously duplicates another database when --from is supplied.

ploy database create --name "Content"
ploy database create --name "Content copy" --from <databaseId>
ploy database create --name "Content copy" --from <databaseId> --operation-key <uuid> --json

Option	Meaning
`--name <name>`	Required display name for the new database.
`--from <databaseId>`	Duplicates an existing database, including its tables and rows.
`--operation-key <uuid>`	Reuses or rejoins a duplication operation. Requires `--from`. The CLI generates a UUID when omitted.
`--json`	Prints the created database or duplication receipt as JSON.

`ploy database rename <databaseId> --name <name> [--json]`

Changes a database's display name.

ploy database rename <databaseId> --name "Customer content"

<databaseId> identifies the database to rename.
--name <name> is the required new display name.
--json prints the updated database as JSON.

`ploy database archive <databaseId> [--json]`

Archives a database without permanently deleting its stored data.

ploy database archive <databaseId>

`ploy database delete <databaseId> --from-workspace <workspaceId> --confirm-database <databaseId> [--json]`

Permanently archives the selected database for workspace-transfer cleanup and revokes its access tokens. The explicit workspace and confirmation flags must identify the same database you intend to remove.

ploy database delete <databaseId> --from-workspace <workspaceId> --confirm-database <databaseId> --json

Delete a source database only after the destination is verified and no remaining site or external consumer uses it. See the workspace transfer guide.

`ploy database operation <operationId> [--json]`

Reads the status of an asynchronous database or table duplication.

ploy database operation <operationId> --json

Possible statuses are in_progress, succeeded, and failed. A failed operation returns exit code 1.

Tables

`ploy database table list <databaseId> [--json]`

Lists the tables in a database.

ploy database table list <databaseId>

--json prints { "tables": [...] } instead of tab-separated table ID and name lines.

`ploy database table create <databaseId> --name <name> [--json]`

Creates a table using the product's starter columns and placeholder rows.

ploy database table create <databaseId> --name "Contacts"

`ploy database table duplicate <databaseId> <tableId> [options]`

Asynchronously duplicates a table, including its columns and rows.

ploy database table duplicate <databaseId> <tableId> --operation-key <uuid> --json

--operation-key <uuid> reuses or rejoins a duplication operation. The CLI generates a UUID when omitted.
--json prints the duplication receipt as JSON.

Use ploy database operation <operationId> to inspect progress.

`ploy database table rename <databaseId> <tableId> --name <name> [--json]`

Changes a table's name.

ploy database table rename <databaseId> <tableId> --name "Customers"

`ploy database table delete <databaseId> <tableId> [--json]`

Permanently deletes a table, including its columns and rows.

ploy database table delete <databaseId> <tableId>

Columns

`ploy database column list <databaseId> <tableId> [--json]`

Lists a table's columns, including each field ID, label, and type.

ploy database column list <databaseId> <tableId>

--json prints { "columns": [...] } instead of tab-separated field ID, label, and type lines.

`ploy database column add <databaseId> <tableId> --name <name> [options]`

Adds a column to a table. The type defaults to TEXT.

ploy database column add <databaseId> <tableId> --name "Company"
ploy database column add <databaseId> <tableId> --name "Contract value" --type CURRENCY
ploy database column add <databaseId> <tableId> --name "Private notes" --type LONG_TEXT --secret

Option	Meaning
`--name <name>`	Required column name.
`--type <type>`	Column type. Defaults to `TEXT`.
`--secret`	Marks the new column as secret.
`--json`	Prints the created column as JSON.

Supported column types

TEXT
LONG_TEXT
NUMBER
CURRENCY
PERCENT
CHECKBOX
SELECT
MULTI_SELECT
STATUS
PEOPLE
DATE
URL
EMAIL

`ploy database column rename <databaseId> <tableId> <fieldId> --name <name> [--json]`

Changes a column's display name.

ploy database column rename <databaseId> <tableId> <fieldId> --name "Account name"

`ploy database column retype <databaseId> <tableId> <fieldId> --type <type> [--json]`

Changes a column's type and automatically converts all existing values.

ploy database column retype <databaseId> <tableId> <fieldId> --type NUMBER

`ploy database column secret <databaseId> <tableId> <fieldId> <state> [--json]`

Marks or unmarks a column as secret. Set <state> to on or off.

ploy database column secret <databaseId> <tableId> <fieldId> on
ploy database column secret <databaseId> <tableId> <fieldId> off

`ploy database column delete <databaseId> <tableId> <fieldId> [--json]`

Permanently deletes a column and every value stored in it.

ploy database column delete <databaseId> <tableId> <fieldId>

Rows

`ploy database row list <databaseId> <tableId> [options]`

Lists and paginates rows, with optional text search, filters, and ordered sorting.

ploy database row list <databaseId> <tableId>
ploy database row list <databaseId> <tableId> --limit 100 --search "enterprise"
ploy database row list <databaseId> <tableId> --filter <fieldId>:contains:software --sort <fieldId>:asc
ploy database row list <databaseId> <tableId> --cursor <cursor> --json
ploy database row list <databaseId> <tableId> --fields <fieldId>,<fieldId>

Option	Meaning
`--limit <n>`	Maximum rows to return. Must be from `1` through `500`.
`--search <text>`	Case-insensitive substring search across text-based columns.
`--filter <fieldId>:<operator>[:<value>]`	Filters rows. Repeat up to 50 times.
`--sort <fieldId>:<asc\|desc>`	Sorts rows in the supplied order. Repeat up to 10 times.
`--cursor <cursor>`	Continues from the cursor returned by a previous list request.
`--fields <field-ids>`	Returns only these columns. Give 1 to 97 distinct field IDs, separated by commas. Row IDs, paging, filters, and sorting still work, and filters and sorts can use columns you leave out.
`--json`	Prints the complete `{ rows, nextCursor, hasMore }` page as one JSON line.

When continuing with --cursor, repeat the same search, filter, sort, and limit settings from the original query. A cursor used with changed query settings is rejected so you do not accidentally receive the wrong page of results.

Each page can be at most 8 MiB. If a page is larger, the command fails and returns no rows. Lower --limit or return fewer columns with --fields, then run the command again.

Without --json, each row is printed as one JSON object:

{"id":"row_...","values":{"fld_...":"value"}}

Row output uses the values key, the same key that row add and row update use. Each row in --json output uses it too. If a script reads fields, change it to read values.

Supported row filters

Column types	Operators
Text, long text, URL, email	`contains`, `eq`, `neq`, `is_null`, `is_not_null`
Number, currency, percent, date	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `is_null`, `is_not_null`
Select, status, checkbox	`eq`, `neq`, `is_null`, `is_not_null`
Multi-select, people	`list_contains`, `list_not_contains`, `is_null`, `is_not_null`

Filter values may contain colons because the CLI splits only the first two colons. is_null and is_not_null do not accept a value.

`ploy database row add <databaseId> <tableId> [options]`

Adds one row, or a batch of up to 100 rows, to a table. If neither value source is supplied, the command creates an empty row.

ploy database row add pdb_123 tbl_456 --values '{"fld_name":"Ada","fld_active":true}'
ploy database row add <databaseId> <tableId> --file ./row.json
cat ./row.json | ploy database row add <databaseId> <tableId> --file -
ploy database row add <databaseId> <tableId> --values '{"<fieldId>":"Ada"}' --idempotency-key signup-ada
ploy database row add <databaseId> <tableId> --file ./rows.json --json

--values <json> accepts a JSON object keyed by column field ID.
--file <path> reads a JSON object, or an array of 1 to 100 objects, from a file. Use - for standard input.
--values and --file are mutually exclusive.
--json prints the created row as JSON. For a batch, it prints { "rows": [...], "inserted": <n> }.

--idempotency-key <key> makes a retry safe. Use 1 to 128 characters. If you run the add again with the same key, Ploy returns the row it already created and does not change it. Use one key for one row. After you delete that row, the same key can create it again.

To add several rows in one step, pass an array of objects with --file. --values accepts only one object. Ploy adds every row in the batch or none of them, and returns the rows in the order you gave. If you run the same batch again, Ploy returns the same rows and adds nothing. A batch with any changed value or a different order counts as a new batch. Without --json, the CLI prints how many rows the batch contains and how many it added.

`ploy database row update <databaseId> <tableId> <rowId> [options]`

Updates selected fields in one row. Fields omitted from the input remain unchanged.

ploy database row update <databaseId> <tableId> <rowId> --values '{"fld_active":false}'
ploy database row update <databaseId> <tableId> <rowId> --file ./changes.json

Supply exactly one useful value source: a non-empty JSON object through --values, or a file through --file. The two options are mutually exclusive.

`ploy database row upsert <databaseId> <tableId> --match <fieldId>=<value> [options]`

Updates the row whose column exactly matches the value, or adds a row when none matches. Ploy matches and writes in one step, so retries and parallel runs do not create duplicates.

ploy database row upsert <databaseId> <tableId> --match <fieldId>=launch-post --values '{"<fieldId>":"Launch post"}'
ploy database row upsert <databaseId> <tableId> --match <fieldId>=42 --file ./row.json --json

--match <fieldId>=<value> is required. The value must be text, a number, or true or false. To match text that looks like a number, quote it as JSON, for example --match '<fieldId>="42"'.
When a row matches, only the fields you supply change. Other fields keep their values.
When no row matches, the new row also stores the match value.
If more than one row matches, the command fails and changes nothing.
--values, --file, and --json work as they do for row add. --file accepts one object, not an array.

`ploy database row delete <databaseId> <tableId> <rowId> [--json]`

Deletes one row.

ploy database row delete <databaseId> <tableId> <rowId>

CSV export

`ploy database export <databaseId> <tableId> [options]`

Exports table data as CSV. By default, the CSV is written to standard output. The command requires workspace membership and access to the database.

ploy database export <databaseId> <tableId>
ploy database export <databaseId> <tableId> --file ./records.csv
ploy database export <databaseId> <tableId> --search "enterprise" --filter <fieldId>:contains:software --sort <fieldId>:asc
ploy database export <databaseId> <tableId> --json

Option	Meaning
`--file <path>`	Writes the CSV to a file instead of standard output.
`--search <text>`	Applies the same text search used by `row list`.
`--filter <fieldId>:<operator>[:<value>]`	Applies the same repeatable filters used by `row list`.
`--sort <fieldId>:<asc\|desc>`	Applies the same repeatable ordered sorting used by `row list`.
`--json`	Emits the CSV plus export metadata as JSON.

Export includes all matching rows across pagination, up to 10,000 rows. If the result is truncated, the CLI writes a warning to standard error so redirected CSV output stays clean.

CSV export is for interchange, not a lossless backup or a consistent snapshot while records are changing. Options export as labels, list values use semicolons, checkboxes use true/false, and files export only their names. Exact option identity, labels that contain separators, file references, empty versus null values, and formula-like text may not round-trip exactly through a re-import. See Database for the dashboard workflow.

CSV import

`ploy database import <databaseId> (--table-name <name> | --table-id <tableId>) [options]`

Imports a CSV into a newly created or existing table and automatically determines column types.

ploy database import <databaseId> --table-name "Records" --file ./records.csv
ploy database import <databaseId> --table-id <tableId> --file ./records.csv --dry-run
cat ./records.csv | ploy database import <databaseId> --table-name "Records" --idempotency-key <key>

Option	Meaning
`--table-name <name>`	Creates a new table with this name and imports into it.
`--table-id <tableId>`	Imports into an existing table.
`--file <path>`	Reads CSV from a file. When omitted, reads CSV from standard input.
`--idempotency-key <key>`	Sets an explicit retry-deduplication key. When omitted, the CLI derives a stable key from the target, headers, and rows.
`--dry-run`	Validates and describes the import without writing data.
`--json`	Prints the import result as JSON.

Give exactly one of --table-name or --table-id. The first CSV row is treated as the header.

Get built-in help

ploy database --help
ploy database create --help
ploy database table --help
ploy database column --help
ploy database row --help
ploy database export --help
ploy database import --help

Keep going

Check the complete CLI contract for global options, environment variables, saved state, and exit codes.
Bring an existing Astro repository into Ploy using the supported toolchain and publish contract.
Manage workspaces and sites, including domains, routing, publishing, and Code Sync.
Move a site between workspaces with dependency checks, destination validation, traffic cutover, and separate cleanup.
Equip local agents with Ploy skills and inspect a site's design-system context.
Run the CLI from remote agents and CI with API tokens and non-interactive commands.