requests run

Use dynomate-cli requests run to run one DNML request from a terminal or a script. The CLI validates and runs the request as the app does.

The CLI uses the AWS profile from profileName in the request. See AWS credentials.

version = "1.0"name = "find-and-update-order"description = "Find the most recent order for an account, mark it reviewed, and read it back."[variables]accountId = "account#42"pageSize = "1"[defaults]profileName = "commerce-dev"[[dynamodb.query]]name = "Find recent order"tableArn = "arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders"keyConditionExpression = "accountId = :accountId"limit = "${cast(pageSize, 'integer')}"scanIndexForward = false[dynamodb.query.expressionAttributeValues]":accountId" = "${accountId}"[[dynamodb.update]]name = "Mark reviewed"dependsOn = "Find recent order"tableArn = "arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders"updateExpression = "SET #status = :status"[dynamodb.update.keyValues]accountId = "${accountId}"orderId = "${find_recent_order.items[0].orderId}"[dynamodb.update.expressionAttributeNames]"#status" = "status"[dynamodb.update.expressionAttributeValues]":status" = "REVIEWED"[[dynamodb.get]]name = "Read back"dependsOn = "Mark reviewed"tableArn = "arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders"consistentRead = true[dynamodb.get.keyValues]accountId = "${accountId}"orderId = "${find_recent_order.items[0].orderId}"

Identify the request

By file

Give the path to a .dnml file. It does not have to be in a collection.

By collection and name

Give the collection folder with --collection and the request name with --request.

The folder must contain a collection.dnml marker. Migrate a legacy collection first.

Use only one form. Other combinations stop with exit code 2.

Relative paths in the request start from the folder of the request file.

Options

Write option values as --format json or --format=json.

Inputs

The CLI reads values from three sources. A later source wins:

1. --global-env NAME: a global environment from the app data directory.
2. --collection-env NAME: the file environments/NAME.json in the collection of the request.
3. --input NAME=VALUE: a value on the command line.

The CLI loads only enabled environment variables.

Request variables win

Variables in [variables] override all three sources. To set a value from the command line, do not declare it there.

Input rules

• Values are always strings. For other types, use a cast, for example ${cast(pageSize, 'integer')}.
• A name starts with a letter or an underscore, and contains only letters, digits and underscores.
• The value is the text after the first =. If a name repeats, the last value wins.
• Templates cannot read environment variables. Pass them as --input REGION="$AWS_REGION".

If an input is not valid, the CLI stops with exit code 2 and runs nothing:

Missing inputs

If no source gives a name that a template uses, validation fails and no operation runs. Here, nothing gives accountId:

With --format json, the DNML_UNRESOLVED_TEMPLATE error details also show the operation and field. A missing environment fails with ENVIRONMENT_NOT_FOUND.

Approval

The approval rules are the same as for the Confirm request dialog in the app. --approval sets when the CLI asks:

With auto, these do not need approval:

• Item writes and deletes, for example dynamodb.update.
• Endpoints saved on an AWS profile.
• Disabled operations and their dependents.
• Amazon Aurora DSQL operations, also with the admin role.

Approval does not skip validation, endpoint rules or table guards.

In a terminal

The CLI asks only if standard input and standard error are both a terminal. It shows the request name, table actions, endpoints and Aurora DSQL connections. It also asks if you redirect standard output.

At the [y/N] prompt, type y or yes to run the request. Any other answer fails it with APPROVAL_FAILED.

Without a terminal

In a script or a CI job, a request that needs approval fails before any operation runs. This request uses a saved profile endpoint, so only its table action needs approval:

version = "1.0"name = "truncate-orders"description = "Clear every item from the local Orders table."[defaults]profileName = "commerce-dev"[[dynamodb.truncate]]name = "Clear orders"tableArn = "arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders"guard = { expectTableName = "Orders", expectItemCountAtMost = 100 }

Table actions:  Clear orders (dynamodb.truncate): arn:aws:dynamodb:ap-southeast-2:111122223333:table/Orders; guard: {"expectItemCountAtMost":100,"expectTableName":"Orders"}Endpoints:  Clear orders (dynamodb.truncate, operation): dynamodb endpoint http://localhost:8000; profile: commerce-dev; region: ap-southeast-2; source: saved profile

To run it in automation, use --approval never.

Output formats

The result goes to standard output, except for argument errors. The endpoint summary, the connection summary and the approval prompt go to standard error.

Pretty

The default format shows the request status, then one line for each operation with its status and its result, error or skip reason. The running example uses this format.

If validation fails, the CLI also shows the file location when it knows it:

Aurora DSQL results

The pretty format shows the results of Aurora DSQL operations as row tables and summary lines.

This run uses the settle-order.dnml example:

• If the server sent more rows than maxRows, the rows: line adds (more not collected: maxRows).
• dsql.listSchemas, dsql.listTables and dsql.describeTable show the result as compact JSON.
• With --format json, the CLI prints the full result, with the PostgreSQL type of each column.

JSON

--format json prints one JSON document with the request status, times, error and the outcome of each operation. This is the same validation failure:

{  "version": "1.0",  "request": "find-and-update-order",  "status": "failed",  "startedAt": "2026-09-23T06:46:35.620Z",  "finishedAt": "2026-09-23T06:46:35.620Z",  "error": {    "code": "DNML_UNKNOWN_DEPENDENCY",    "message": "operation depends on an unknown operation name",    "details": {      "code": "DNML_UNKNOWN_DEPENDENCY",      "message": "operation depends on an unknown operation name",      "path": "./bad/find-and-update-order.dnml",      "operation": "Mark reviewed",      "field": "dependsOn",      "line": 23,      "column": 1    }  },  "outcomes": []}

For the fields and how to parse them, see JSON output.

Endpoint summary

If a request uses a custom endpoint, the CLI writes an Endpoints: summary to standard error on each valid run. After a prompt, the CLI does not write the summary, because the prompt shows the endpoints.

Endpoints:  Find recent order (dynamodb.query, operation): dynamodb endpoint http://localhost:8000; profile: commerce-dev; region: ap-southeast-2; source: saved profile  Mark reviewed (dynamodb.update, operation): dynamodb endpoint http://localhost:8000; profile: commerce-dev; region: ap-southeast-2; source: saved profile  Read back (dynamodb.get, operation): dynamodb endpoint http://localhost:8000; profile: commerce-dev; region: ap-southeast-2; source: saved profile

• source: saved profile: the endpoint comes from the saved AWS profile.
• source: request-defined: the request contains the endpoint.

Connection summary

If a request has Aurora DSQL operations, the CLI writes a Connections: summary to standard error after the run. It has one line for each operation, with the cluster, the AWS Region, the database role, the route and the TLS level.

For the settle-order.dnml run, with no saved data for the cluster, standard error shows:

Connections:  Load order  exampleclusterid0123456789 (us-east-1) as app_writer · public · TLS verified  Settle      exampleclusterid0123456789 (us-east-1) as app_writer · public · TLS verified  Read back   exampleclusterid0123456789 (us-east-1) as app_writer · public · TLS verified

• The route and the TLS level come from the saved network settings of the cluster.
• If the cluster ARN or the role comes from an earlier result, the line shows cluster resolved during run or role resolved during run.
• After a prompt, the CLI does not write the summary, because the prompt shows the connections.

Exit codes

A request can exit with 1 after some operations ran. In this partial run, the query finds no order, so Mark reviewed fails:

Dynomate does not roll back changes.

Cancel a run

Press Ctrl + C to cancel a request. The CLI stops the request as Cancel in the request toolbar does, then prints the result:

• The request fails with DNML_CANCELLED and exit code 1.
• The current operation fails. Dynomate skips the operations that did not start, with the reason stopped.
• Dynomate does not undo completed writes.

For Aurora DSQL, Ctrl + C closes the connection of the current operation. After its error, a failed Aurora DSQL operation can show these lines:

  commit: committed  commit: rolled back (no changes were kept)  commit: unknown (may or may not have committed; check the data before running this again)  transaction ended by statements[0] (its own COMMIT or ROLLBACK)

If the line says commit: unknown, check the data before you run the request again. See Unknown commit outcomes.