CLI and API: controlled access and checks

Prepare the client

Download the distribution for your operating system from Developer Tools and compare its checksum with the published value. Treat that distribution's help as the reference for its commands. The CLI version can differ from the platform version; a package filename alone does not establish compatibility or integrity.

The CLI authenticates with a personal Dova API key. Create it through the authorized API Keys interface and keep its value in a private mechanism. This is not an OpenAI key. Avoid placing keys or passwords in command arguments, screenshots, shared files or histories. Interactive login prompts for the key without displaying it. Use an operating-system account appropriate for the work you are performing.

Read before changing anything

These commands contain no secrets and inspect the current context:

dova --version
dova --help
dova login
dova status --output json
dova repository list --output json
dova mapping list --output json
dova workflow list --output json
dova run list --output json
dova logout

dova login uses the public service configured by the distribution. Verify that status shows the intended tenant before executing actions with effects. The CLI saves authentication configuration locally; protect your operating-system account and log out when appropriate. Closing the terminal does not revoke a personal key.

Run an authorized test

The help for dova workflow run --help describes inputs, parameters and waiting. First select a published laboratory Workflow with accepted dependencies. The --wait option observes the attempt; a client timeout does not prove execution has ended. Check Monitor before resubmitting. The cancel, terminate, rerun and recover commands have different consequences and current-state checks.

Distinguish authentication flows

The web-session API retains login, MFA when required, a cookie and CSRF protection for changes. If login returns authenticated:false with mfaRequired:true, MFA is still incomplete; HTTP 200 does not mean authentication finished. After successful MFA, inspect the session and use its current CSRF value for the relevant web flow.

A CLI Bearer personal key does not become a web session and does not replace MFA for global DovaAI provider configuration. That setting belongs to the uniquely authorized master user through its protected flow. Do not copy browser cookies into commands.

Check results and errors

For 401, inspect the credential or session; for 403, inspect the role and tenant. A validation error requires correcting the indicated resource, not blindly repeating writes. Keep safe attempt identifiers for diagnosis without logging authentication headers. Verify an accepted response in the corresponding object or execution attempt.

Export an environment promotion for Git/DevOps

Configuration → Environment promotions can export the manifest of an applied release. The GitOps kit adds promotion-export --release-id <id> --output dova/promotion-release.json through app/bin/dova_gitops.py, using its authorized configuration and authentication. This command reads the release, verifies its digest and writes a local file; it does not promote, execute or modify Dova or Git.

Run it from the local repository prepared for the kit. Review the manifest before recording it in version control: it retains published artifacts, dependencies and provenance; secret references become placeholders. Recording repository, commit and tag does not authenticate a remote repository or push commits. GitHub remains a repository and GitHub Actions is not activated.

Environment context

Before using this module, confirm Tenant, Domain and Environment in the user menu. The initial environment is Development. Module, Domain and environment capabilities apply together; Production is read only without explicit authorization. Switching the selector does not move artifacts or publish or execute their data. See environments and recovery and environment promotion.

GitOps 1.1.2: bind the source and target

Download the GitOps kit 1.1.2 from an authorized Developer Tools session and compare the published SHA-256. Extract dova_gitops.py, dova-gitops.example.json and README.md into your local repository. Use Python 3.12 or later and personal keys through the protected variables named by apiKeyEnv; keep their values out of Git.

In dova-gitops.json, source.environment and source.domainId select the export source. target.environment selects the destination and bindings.domainId is its authoritative Domain. When present, target.domainId must match bindings.domainId. The tenant remains the one authorized by the personal key and must match the configuration; these fields neither change tenant nor grant access.

Omitted environment values use development; the default Domain is General (dom_general). Set the context explicitly for another Domain. Version 1.1.2 binds the Domain from bindings before the first query and retains the same Tenant, Domain and Environment for reads, draft reservations, saves, publications and edit-lease acquisition or release. Do not change the context of a client that has already sent requests.

Synthetic example: Finance in Test

This fragment extends the kit example. Replace the IDs with an existing authorized Domain and Folder; it does not create Finance or its resources:

{
  "source": {"environment": "development", "domainId": "dom_finance"},
  "target": {"environment": "test", "domainId": "dom_finance"},
  "bindings": {"domainId": "dom_finance", "folderId": "fld_REPLACE_WITH_EXISTING_FINANCE_FOLDER"},
  "statePath": "dova/target-state-finance-test.json"
}

Also configure URL, tenant, key-variable names and any Connection, worker, profile or file bindings required by the bundle. From the local repository, validate and review before an authorized import:

python dova_gitops.py --config dova-gitops.json validate
python dova_gitops.py --config dova-gitops.json plan --plan-file dova/plan.json
python dova_gitops.py --config dova-gitops.json apply --plan-file dova/plan.json

validate checks the local bundle. plan reads the target without writing. apply creates or updates definitions and publishes the reviewed versions in Development, Test or Stage. Published source versions and their environment labels remain unchanged. Direct Production authoring is rejected before requests with production_authoring_requires_environment_promotion; use Dova's governed environment promotion for that destination.

Preserve state and resolve a wrong context

Use a separate statePath per target. State binds the origin, tenant, Domain and Environment; reuse in another workspace is rejected before querying Dova. An empty older state can adopt the selected context. A populated earlier state without scope requires manual reconciliation of its IDs and published versions. Preserve state and the journal when a write outcome is uncertain: never delete them or change their context fields to force another import.

If a Finance import attempts to use General, check source.domainId, target.environment and bindings.domainId, install kit 1.1.2 and generate a new plan. Historical kits 1.1.0 and 1.1.1 retain their original bytes; 1.1.2 is the workspace-scoped distribution for Dova 24.