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.

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}"

$ dynomate-cli requests run ./orders/find-and-update-order.dnml
find-and-update-order: success
Find recent order: success
  result: {"count":1,"items":[{"accountId":"account#42","orderId":"order#9812","status":"PENDING","total":42}],"lastEvaluatedKey":"eyJvcmRlcklkIjp7IlMiOiJvcmRlciM5ODEyIn0sImFjY291bnRJZCI6eyJTIjoiYWNjb3VudCM0MiJ9fQ==","pages":1,"requestId":"1f999a0f-0ec9-4dba-bd58-c012239a26db","scannedCount":1}
Mark reviewed: success
  result: {"attributes":{"accountId":"account#42","orderId":"order#9812","status":"REVIEWED","total":42},"requestId":"38ea89c4-6e57-48d5-a038-66ab17034323"}
Read back: success
  result: {"found":true,"item":{"accountId":"account#42","orderId":"order#9812","status":"REVIEWED","total":42},"requestId":"d2946fe3-e6b1-4ede-a4ce-aa4cd1365319"}

Identify the Request

By File

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

$ dynomate-cli requests run ./orders/find-and-update-order.dnml

By Collection and Name

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

$ dynomate-cli requests run --collection ./orders --request find-and-update-order

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.

$ dynomate-cli requests run --collection ./orders --request get-orders \
    --global-env development \
    --collection-env local \
    --input REGION=us-east-1 \
    --input ORDER_ID=order-123

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.
• The CLI does not read shell variables. Give them as --input REGION="$AWS_REGION".

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

$ dynomate-cli requests run ./orders-input/find-and-update-order.dnml --approval never --input account-id=account#99
--input names must match [A-Za-z_][A-Za-z0-9_]*

Missing Inputs

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

$ dynomate-cli requests run ./orders-input/find-and-update-order.dnml --approval never
find-and-update-order: failed
  DNML_UNRESOLVED_TEMPLATE: Expression reference is unavailable

With --format json, the 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.

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 and endpoints. 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 }

$ dynomate-cli requests run ./orders-profile/truncate-orders.dnml --approval auto
truncate-orders: failed
  APPROVAL_FAILED: This request requires terminal approval. Run interactively or select --approval=never to proceed without prompts.

Standard error:

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 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:

$ dynomate-cli requests run ./bad/find-and-update-order.dnml --approval never
find-and-update-order: failed
  DNML_UNKNOWN_DEPENDENCY: operation depends on an unknown operation name
  at ./bad/find-and-update-order.dnml:23:1

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:

$ dynomate-cli requests run ./bad/find-and-update-order.dnml --approval never --format json

{
  "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.

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-cli requests run ./orders-input/find-and-update-order.dnml --approval never --input accountId=account#99
find-and-update-order: partial
Find recent order: success
  result: {"count":0,"items":[],"lastEvaluatedKey":null,"pages":1,"requestId":"323854f7-b567-40db-bca9-3674c181f255","scannedCount":0}
Mark reviewed: failed
  DNML_UNRESOLVED_TEMPLATE: Expression reference is unavailable
Read back: skipped (dependency-failed)

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 app 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.