docs(cli): add scripted submit/wait/download workflow to CLI help by andychoquette · Pull Request #1264 · aws-deadline/deadline-cloud

andychoquette · 2026-07-09T22:03:06Z

Improves the deadline CLI help so an AI agent (or a human scripting the CLI) can discover the end-to-end job workflow without trial and error:

Top-level overview + bundle/job group help now show the submit -> wait -> download-output sequence with copy-pasteable, non-interactive (--yes) examples.
job wait is documented as the recommended completion signal (blocks; exit 0 = success) instead of polling job get.
bundle submit explains job-attachment storage-profile prompts and how to suppress them (--known-asset-path / --yes); job download-output documents --ignore-storage-profiles for same-machine submit+download.
queue paramdefs is called out as the way to discover queue environments (e.g. Conda), since there is no dedicated list subcommand.

Additive (existing help preserved). Generated and A/B-proven by an eval harness: against a real Blender render task at k=5, the revised help cut the agent's median cost ~11% (fewer exploratory commands / turns) with success held at 100%.

Fixes: N/A (no linked issue)

What was the problem/requirement? (What/Why)

The deadline CLI --help is the primary interface for both humans scripting the CLI and, increasingly, AI agents driving it. The end-to-end job workflow — author a bundle, submit, wait for completion, download output — was not discoverable from the help text: job wait wasn't surfaced as the completion signal (so callers polled job get in a loop), the job-attachment storage-profile prompt (which cancels submission for paths outside the storage profile) was unexplained, and there was no pointer that queue paramdefs is how you inspect a queue's environments (e.g. Conda). Agents burned extra commands and turns rediscovering this each time.

What was the solution? (How)

Clarify the affected command/group --help text and docstrings. Changes are additive — existing help, examples, and doc links are preserved; new content adds the workflow sequence, concrete non-interactive examples, and the specific gotchas above. Scope: help strings only in _main.py and _groups/{bundle,job,queue}_group.py. Every added claim was verified against the CLI's own implementation (exit codes, option existence, settings.known_asset_paths, queue subcommands, job get output fields) — no invented flags or behavior.

What is the impact of this change?

Clearer, self-describing CLI help — fewer commands and less trial-and-error for anyone (human or agent) running an end-to-end job. No functional, argument, or behavioral change.

How was this change tested?

Verified the rewritten help renders correctly (Click \b blocks intact, no formatting regressions) via CliRunner().invoke(cmd, ["--help"]) for the affected commands.
Every factual claim in the new text was cross-checked against the current CLI source (exit-code mapping in job wait, --ignore-storage-profiles on submit/download, the five queue subcommands, job get output fields, the settings.known_asset_paths config key).
The change is limited to help= strings and command docstrings — no code paths, arguments, types, or defaults were modified.
Have you run the unit tests? — Change is help-text-only with no test logic touched; the standard suite should be confirmed by CI.
Have you run the integration tests? — No.

Was this change documented?

Are relevant docstrings in the code base updated? — Yes; this PR is the docstring/help update.
Has the README.md been updated? — Not required; no CLI arguments, flags, or behavior changed (help text only).

Does this PR introduce new dependencies?

This PR does not add any new dependencies.

Is this a breaking change?

No. Only --help/docstring text changed; no public contract is affected.

Does this change impact security?

No. No files/directories, permissions, or trust boundaries are created or modified.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Improves the `deadline` CLI help so an AI agent (or a human scripting the CLI) can discover the end-to-end job workflow without trial and error: - Top-level overview + `bundle`/`job` group help now show the submit -> wait -> download-output sequence with copy-pasteable, non-interactive (--yes) examples. - `job wait` is documented as the recommended completion signal (blocks; exit 0 = success) instead of polling `job get`. - `bundle submit` explains job-attachment storage-profile prompts and how to suppress them (--known-asset-path / --yes); `job download-output` documents --ignore-storage-profiles for same-machine submit+download. - `queue paramdefs` is called out as the way to discover queue environments (e.g. Conda), since there is no dedicated list subcommand. Additive (existing help preserved). Generated and A/B-proven by an eval harness: against a real Blender render task at k=5, the revised help cut the agent's median cost ~11% (fewer exploratory commands / turns) with success held at 100%. Signed-off-by: Andy Choquette <78888816+andychoquette@users.noreply.github.com>

crowecawcaw · 2026-07-09T23:38:47Z

What about adding --wait and --download-on-success flags to the submit command instead?

andychoquette · 2026-07-13T15:57:54Z

yeah, i think thats reasonable. I'll make the update. Will also adjust the evals system prompt to make explicit that new flags are allowed if they meaningfully improve agent performance.

github-actions · 2026-07-14T15:16:45Z

+                # Imported lazily to avoid a circular import with job_group.
+                from .job_group import _download_job_output
+
+                _download_job_output(


--download-on-success calls _download_job_output, which only skips the interactive "confirm root paths" prompt when settings.auto_accept is true (see job_group.py if not auto_accept: _prompt_to_confirm_roots(...)). That config value is only set to true when --yes is passed to this command. So deadline bundle submit ./bundle --download-on-success (without --yes) will submit, wait, then block on an interactive prompt during the download — defeating the "one command for scripts/agents" purpose this feature is built for.

Consider either forcing auto-accept for the implied download here, or documenting in the --download-on-success help that --yes is required for a fully non-interactive run.

Collapses the common submit -> wait -> download-output sequence into a single `deadline bundle submit` invocation, so scripts and agents don't have to chain three commands and thread the job id between them: - --wait: after submit, block until the job reaches a terminal state (reusing api.wait_for_job_completion, the same path `deadline job wait` uses) and exit non-zero if it does not succeed. - --download-on-success: implies --wait; on SUCCEEDED, download the job's output (reusing job_group._download_job_output, the same path `deadline job download-output` uses). Both are additive and default off -- existing behavior is unchanged. They no-op when there is no real job (e.g. --save-debug-snapshot yields no job id). Adds unit tests covering the non-success exit and the download-on-success path. Signed-off-by: Andy Choquette <78888816+andychoquette@users.noreply.github.com>

github-actions · 2026-07-15T22:35:02Z

+            farm_id = config_file.get_setting("defaults.farm_id", config=config)
+            queue_id = config_file.get_setting("defaults.queue_id", config=config)
+            click.echo(f"Waiting for job {job_id} to complete...")
+            result = api.wait_for_job_completion(


The new --wait / --download-on-success block runs inside the submission try, so failures that happen after the job is already created get reported as submission failures. For example, if _download_job_output raises a ClientError (it calls deadline.get_job, S3 ops, etc.), it lands in the except ClientError handler below and is re-raised as "Failed to submit the job bundle to AWS Deadline Cloud" — even though the job submitted fine and is running. Likewise the generic except Exception records this as an "on_submit" telemetry error.

For a scripted workflow this is misleading: a non-zero exit + "submission failed" message could prompt a caller to resubmit and create a duplicate job. Consider moving the wait/download after the try/except/finally (once submission has definitively succeeded), or wrapping it in its own try/except with a distinct error message.

crowecawcaw

Follow up idea: make the failure case excellent for agents as well. Today when iterating on a job, you need to submit, wait, then get logs. Getting the logs is not totally obvious since there are multiple sessions, statuses, etc. If a job fails, the most important info probably are the task statuses and the last 50 lines or so of the last task that failed. It'd be cool if an agent had all the info it needed after submitting a job that fails to fix the issue and submit again, without a second command.

crowecawcaw · 2026-07-16T15:36:42Z

+    Scripted workflow (no prompts):
+      deadline bundle submit ./bundle --yes
+      deadline job wait --job-id <id>
+      deadline job download-output --job-id <id> --yes


Nit: let's recommend the new flags!

crowecawcaw · 2026-07-16T15:38:40Z

+    \b
+    For scripted workflows, prefer `wait` over polling `get`:
+      deadline job wait --job-id <id>       # blocks, exit 0 = success
+      deadline job download-output --job-id <id> --yes
+


Feels like this string is too specific for the higher leveljob command. Maybe put some example commands that include wait in here.

crowecawcaw · 2026-07-16T15:39:27Z

+    \b
+    Pass --yes to skip confirmation prompts (useful when scripting).
+    Pass --ignore-storage-profiles when submitting and downloading on the
+    same machine to skip storage profile path mapping.


Aren't these flags documented when you call --help already?

crowecawcaw · 2026-07-16T15:40:47Z

+    \b
+    Available subcommands:
+      list               List queues in the farm
+      get                Get details of a queue (incl. job attachment settings)
+      paramdefs          List parameters from queue environments (e.g. conda)
+      export-credentials Export temporary queue role credentials
+      sync-output        Incrementally download output for all jobs in queue
+
+    \b
+    Note: There is no subcommand for listing queue environments directly.
+    Use `deadline queue paramdefs` to see what parameters (and therefore
+    which queue environments such as Conda) are configured on a queue.
+


Don't think this is necessary. The current help text looks like:

$ deadline queue --help Usage: deadline queue [OPTIONS] COMMAND [ARGS]... Manage Deadline Cloud queues. View queue details, list available queues, export queue credentials for scripting, inspect queue parameter definitions, or sync job output for all jobs in a queue. Learn more about queues (https://docs.aws.amazon.com/deadline-cloud/latest/userguide/queues.html) Options: -h, --help Show this message and exit. Commands: export-credentials Export queue credentials in a format compatible... get Get the details of a Deadline Cloud queue in the farm. list Lists the available Deadline Cloud queues in the farm. paramdefs Lists the parameter definitions for a Deadline... sync-output Downloads any new job attachment output for all...

crowecawcaw · 2026-07-16T15:41:26Z

+    Scripted end-to-end example (no interactive prompts):
+      deadline bundle submit ./bundle --yes
+      deadline job wait --job-id job-abc123
+      deadline job download-output --job-id job-abc123 --yes


Replace with our new command

github-actions Bot added the waiting-on-maintainers Waiting on the maintainers to review. label Jul 9, 2026

Merge branch 'mainline' into docstrings/agent-workflow-help

4cf2fdc

andychoquette marked this pull request as ready for review July 9, 2026 22:33

andychoquette requested a review from a team as a code owner July 9, 2026 22:33

karthikbekalp previously approved these changes Jul 9, 2026

View reviewed changes

leon-li-inspire previously approved these changes Jul 9, 2026

View reviewed changes

andychoquette dismissed stale reviews from leon-li-inspire and karthikbekalp via eb43889 July 14, 2026 15:10

github-actions Bot reviewed Jul 14, 2026

View reviewed changes

andychoquette force-pushed the docstrings/agent-workflow-help branch from eb43889 to 83e050e Compare July 14, 2026 15:32

Merge branch 'mainline' into docstrings/agent-workflow-help

f8d54bf

github-actions Bot reviewed Jul 15, 2026

View reviewed changes

crowecawcaw reviewed Jul 16, 2026

View reviewed changes

andychoquette marked this pull request as draft July 20, 2026 15:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(cli): add scripted submit/wait/download workflow to CLI help#1264

docs(cli): add scripted submit/wait/download workflow to CLI help#1264
andychoquette wants to merge 4 commits into
aws-deadline:mainlinefrom
andychoquette:docstrings/agent-workflow-help

andychoquette commented Jul 9, 2026

Uh oh!

crowecawcaw commented Jul 9, 2026

Uh oh!

andychoquette commented Jul 13, 2026

Uh oh!

github-actions Bot Jul 14, 2026

Uh oh!

github-actions Bot Jul 15, 2026

Uh oh!

crowecawcaw left a comment

Uh oh!

crowecawcaw Jul 16, 2026

Uh oh!

crowecawcaw Jul 16, 2026

Uh oh!

crowecawcaw Jul 16, 2026

Uh oh!

crowecawcaw Jul 16, 2026

Uh oh!

crowecawcaw Jul 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

andychoquette commented Jul 9, 2026

What was the problem/requirement? (What/Why)

What was the solution? (How)

What is the impact of this change?

How was this change tested?

Was this change documented?

Does this PR introduce new dependencies?

Is this a breaking change?

Does this change impact security?

Uh oh!

crowecawcaw commented Jul 9, 2026

Uh oh!

andychoquette commented Jul 13, 2026

Uh oh!

github-actions Bot Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

crowecawcaw left a comment

Choose a reason for hiding this comment

Uh oh!

crowecawcaw Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

crowecawcaw Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

crowecawcaw Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

crowecawcaw Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

crowecawcaw Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants