CLI and API: controlled, verifiable automation

The CLI can inspect authorized objects and runs and launch permitted actions. This chapter uses command shapes and routes reviewed in the current client; it is not a complete OpenAPI specification or a promise that every internal route is a stable public integration. Check your installed client's help before automating against a different release.

1. Download, verify and identify the client

Open Developer Tools, select the distribution for your platform and inspect version, signature status and SHA-256. Calculate the downloaded artifact hash and compare it exactly. Install using the distribution instructions, then run dova --version to identify the executable on your PATH.

2. Authenticate to an authorized laboratory

Create a personal API key for the exercise, then log in interactively:

dova login --url https://dova-lab.example.invalid

The .invalid host is a nonfunctional placeholder. Replace it with your permitted laboratory environment. Enter the key through the prompt, not a shared command argument. Verify the reported identity and tenant before continuing. Protect the local CLI profile because it stores authentication configuration.

3. Start with read-only operations

dova status --output json
dova repository list --domain Training --output json
dova mapping list --name sample --limit 50 --output json
dova workflow list --status published --name sample --output json
dova run list --status failed,cancelled --sort createdAt --descending --output csv

Compare identifiers with Repository, Workflows and Monitor. An empty filtered collection can be correct; a failed request must not be converted to a valid empty list. JSON is useful for explicit field processing and CSV for an authorized tabular review. Names are not guaranteed to be unique.

4. Understand the reviewed route shapes

The client uses Bearer authentication and JSON responses. Collection keys differ: Workflows use orchestrations, while attempts use runs. For direct API integrations, confirm the actual response schema and retain normal authorization, failure and tenant handling.

5. Run a published synthetic example

The local laboratories require no network. A server run is a second phase and can write outputs, so first prepare published definitions, authorized inputs and a laboratory-only destination.

dova workflow run WORKFLOW_ID --input transform_workflows/inputs/customers.csv --wait --output json

For multiple sources, repeat --source using TASK_ID:SOURCE_NODE_ID=FILE:

dova workflow run WORKFLOW_ID --source TASK_ID:source_txt=transform_workflows/inputs/transactions.txt --source TASK_ID:source_xlsx=transform_workflows/inputs/customers.xlsx --wait --output json

Replace placeholders with the actual identifiers from your published definition. Do not combine --input and --source. The client also supports --var KEY=VALUE and --param KEY=VALUE for permitted values that match the Workflow contract. Keep secrets out of ordinary overrides.

6. Wait, verify and close

--wait polls toward a terminal state; --poll and --wait-timeout bound its behavior. A client timeout does not establish server cancellation. Query the attempt again before repeating, cancelling or recovering it. Compare the generated output with the independent expected data, not just the terminal command status.

Record client version, environment, object/run identifiers, safe parameters, terminal state and result comparison. Use dova logout to remove local authentication state when done, and revoke a temporary key in the UI when it should cease working everywhere. Revocation and local logout are distinct operations.