CLI reference

dagy --help
dagy --version
dagy deploy --help

Global options

Place global options before the command: dagy -e staging deployments list.

Verbose and quiet are mutually exclusive. Most hosted leaf commands accept --profile NAME; see their --help. run, backfill, secrets, and schedules create have command-level --environment options: put the environment after those commands.

Many list commands support --format table|json|yaml|csv. The default is table. Empty lists can produce a human-readable message instead of an empty JSON document; use the HTTP API for strict machine-to-machine output contracts.

Authentication and profiles

dagy config
dagy login --profile work
dagy whoami
dagy logout --profile work

config opens interactive profile management. login opens the browser for workspace authorization; it saves credentials but does not create a profile. whoami displays saved identity, environment, and known expiration. logout removes credentials and attempts server revocation.

Configure the API URL before hosted operations. Read authentication and profiles for credential acquisition, organization selection, environment precedence, and custom workspace URLs.

Build

dagy build order_pipeline.py:order_pipeline --output-dir dist --param source=sample

The target is a file path followed by : and the decorated flow's Python variable name. --output-dir is optional; default ~/.dagy/builds. Repeat --param key=value for multiple build parameters. --profile is accepted but building is local.

The command prints Artifact: .../artifact.zip. Use that exact path with deploy. The artifact contains the flow source file and graph metadata, not an automatically bundled project or installed third-party dependencies.

Deploy

dagy -e develop deploy PATH_TO_ARTIFACT.zip \
  --deployment orders-develop \
  --execution-mode nano \
  --dry-run

After reviewing the plan, remove --dry-run to deploy. Interactive deployment asks for confirmation; --yes is suitable when your own automation already controls release approval.

An unchanged build can skip deployment even when only schedule, environment, or other deployment options changed. Use the deployment-settings API or --force when those settings must be applied. A missing API URL makes deploy fail; it does not authenticate or select a workspace automatically.

See deployment and dependency packages for preparation and production checks.

Run

For a configured hosted workspace, the positional target is a deployment name:

dagy run orders-develop --environment develop --param source=sample

The command prints a run ID when the request is accepted and does not wait for completion. --execution-mode MODE overrides the deployment tier for this run.

When no API URL is configured, the positional target is a local flow file:

dagy run order_pipeline.py:order_pipeline --max-workers 2 --param source=sample

--max-workers defaults to 1. --no-fail-fast lets independent local tasks continue after a failure. Both options apply to local execution only. There is no run --local; use flow.run_local() to guarantee local execution when you have a hosted profile.

All --param values are strings. --param count=10 passes "10", not 10, and JSON-looking values are not parsed. Use Python calls or JSON API requests for numeric, boolean, list, or object parameters.

Runs and logs

dagy runs list --limit 20
dagy runs list --all-envs --format json
dagy runs list --local --status FAILED
dagy runs show RUN_ID --format json
dagy logs RUN_ID
dagy logs RUN_ID --task TASK_ID

Hosted runs list requests one page. Local --flow filters by a flow-ID substring; hosted --flow sends a flow-name filter. runs show and logs do not retrieve hosted runs even if --profile is present. Use the workspace or runs API for hosted detail and logs.

Flows, deployments, and node types

dagy flows list --limit 100 --format json
dagy deployments list --all-envs --limit 100
dagy nodes list --category ingestion --format json

Flows and deployments default to the active environment. --all-envs removes that filter. flows list follows pagination and treats --limit as page size; deployments list requests one listing. nodes list requires the API and accepts --category, --format, and --profile. See flow listings and node catalog.

Environments and variables

dagy env list
dagy env show staging
dagy env create staging --upstream-env develop --promotion-order 10
dagy env use staging
dagy env current
dagy env vars set staging SOURCE_LABEL validation
dagy env vars list staging
dagy env vars unset staging SOURCE_LABEL

env create NAME also supports --default-executor NAME and --protected. List/show/variable-list commands support formatted output. env use NAME updates the selected profile; an overriding DAGY_ENVIRONMENT variable still takes precedence.

dagy env delete NAME requests deletion and asks for confirmation unless --yes is given. The API can reject deletion when environment protections or existing resources prevent it. See environments for supported environment behavior and permissions.

Promote a deployment

dagy promote orders-develop staging --dry-run
dagy promote orders-develop staging --deployment-name orders-staging

Arguments are source deployment name and target environment. Options are --deployment-name, --profile, --dry-run, and --yes. Review the promotion plan and target environment before applying. Promotion uses the existing artifact; it is not a new local build.

Schedules

dagy schedules list --flow order_pipeline
dagy schedules create \
  --flow order_pipeline \
  --flow-version 1 \
  --deployment orders-develop \
  --environment develop \
  --mode cron \
  --cron '0 9 * * 1-5' \
  --timezone America/New_York
dagy schedules pause SCHEDULE_ID
dagy schedules resume SCHEDULE_ID

List options: --flow, --mode cron|interval|one_time|manual, --limit (100), --format, --profile.

Create options:

There is no schedule-delete CLI command; use the API where supported. See scheduling for calendar behavior, catchup, and schedule verification.

Backfill

dagy backfill \
  --flow order_pipeline \
  --from 2026-01-01T00:00:00Z \
  --to 2026-01-03T00:00:00Z \
  --interval-seconds 86400 \
  --max-concurrency 1 \
  --environment develop \
  --param source=history \
  --dry-run

--flow, --from, and --to are required. --max-concurrency defaults to 1. Set --interval-seconds or --cron to override cadence; otherwise the API derives it from the flow's schedule. Repeat --param for string parameters. --dry-run previews the plan without creating runs. Read backfills before rerunning data-writing workflows.

Secrets

dagy secrets list --environment develop

secrets list returns metadata, not secret values. It supports --environment, --format, and --profile.

dagy secrets set NAME VALUE --environment ENV [--description TEXT] creates or updates a secret. The value is a positional argument, so it can appear in shell history or process listings. Prefer the workspace secret editor or your integration's secret-managed API request when that exposure is unacceptable. The CLI has no standard-input or secret-file option. Read secrets before connecting a credential to a node.

Exit status and troubleshooting

The CLI defines 0 for success, 1 for general failure, 2 for invalid arguments, 3 for configuration errors, 4 for authentication, 5 for API errors, and 6 for not found. Not every handler uses these categories consistently; many command-specific failures return 1, and missing local logs or runs may print a message without a failure exit. Treat nonzero as failure and inspect stderr rather than relying exclusively on fine-grained codes. Keyboard interruption returns 130.

For CI, use --yes only on authorized deployment/promotion actions, set an explicit environment, and verify the resulting hosted resource. Read API errors, profiles, and troubleshooting for recovery steps.