cockpit ask | AGI Cockpit Documentation

This reference is generated from the same canonical source distributed as cockpit CLI help. See Cockpit CLI for concepts and safe operating guidance.

Usage: cockpit ask --summary <text> [--choice <text> [--choice-description <text>]]... [--multiple] [--title <title>] [--directory <path>] [--media <path>]...

Operate open Asks: cockpit ask list [--task <taskId>] / cockpit ask answer <askId> ... / cockpit ask close <askId> | --all | --task <taskId> (see "Operating asks" below).

Schedule a persistent question for the user. The command returns immediately with an Ask ID; Cockpit keeps the question until the user answers or closes it. Answering resumes the same task automatically. Closing removes the Ask without resuming the task. Free-form input is enabled by default for every question.

After a successful cockpit ask, end the current agent turn. Do not poll, call wait, or continue work that depends on the answer. Only one Ask can be active for a task at a time.

cockpit ask --summary "Choose the deployment target" --choice "staging" --choice "production"
cockpit ask --summary "Select checks to run" --choice "lint" --choice "tests" --choice "build" --multiple
cockpit ask --summary "Choose checks" --choice "lint" --choice-description "Fast syntax and style checks" --choice "build" --choice-description "Production build verification" --multiple
cockpit ask --summary "Enter the branch name"
cockpit ask --summary "Release checklist" --question "Deployment target" --question-choice "staging" --question-choice "production" --question "Run migrations?" --question-choice "yes" --question-choice "no"
cockpit ask --summary "Release checklist" --question "Deployment target" --question-choice "staging" --question-choice "production" --question "Checks to run" --question-choice "lint" --question-choice "tests" --question-choice "build" --question-multiple
cockpit ask --summary "Does this design look correct?" --choice "yes" --choice "no" --media screenshot.png
cat summary.md | cockpit ask --stdin --choice "yes" --choice "no"   # Long summary, no shell quoting
cockpit ask --summary-file summary.md --questions-file questions.json
cat questions.json | cockpit ask --summary-file summary.md --questions-stdin

Long summaries and shell quoting:

A summary that spans several lines or contains backticks, quotes, $, or a code fence must not be embedded in --summary "...". The shell runs backticked spans as command substitution and rewrites $... before cockpit receives the argument, so the question arrives damaged, and an unbalanced quote aborts the command so no Ask is created at all. Pass it with --stdin or --summary-file <path> instead; both deliver the text byte for byte.

There is only one standard input, so --stdin fills the summary and --questions-stdin fills the --questions JSON array — use at most one of them per command. To keep both long parts free of the shell, combine --summary-file with --questions-stdin (or use --questions-file). Inside the JSON array, quoting is JSON's problem rather than the shell's, so question summaries, choices, and choice descriptions can contain anything.

Options:

Pass choices with repeated --choice (or --question-choice) flags so each choice is a separate argument.
Add --choice-description immediately after a --choice, or --question-choice-description immediately after a --question-choice, to show explanatory text under that choice.
Bundle related decisions into one dialog with repeated --question "..." --question-choice "..." groups instead of asking one by one. Use --question-multiple after a --question for a per-question multi-select.
--multiple makes the top-level single question multi-select.
--questions '[...]' also accepts a JSON array where each item can include choices: string[], choiceDescriptions: Record<string,string>, and multiple: true. --questions-file <path> and --questions-stdin read the same array without going through the shell.
--summary, --summary-file, and --stdin are mutually exclusive, as are --questions, --questions-file, and --questions-stdin; passing two sources for the same value fails instead of silently picking one. --stdin with nothing piped in fails immediately rather than waiting for input.
--media <path> attaches files and can be repeated. Supported: png, jpg, jpeg, gif, webp, mp3, wav, ogg, aac, m4a, flac, mp4, webm, mov.
Up to 8 media files can be attached. Each file can be up to 512 MB, with a 1 GB total per Ask. Files are uploaded as streams and loaded only when the Ask is viewed.
Legacy --choices "a,b,c" and --question-choices "a,b,c" are comma-separated only; do not use | as a separator.

Writing self-contained asks:

The user answers from the dialog alone — often from a phone notification, without the chat view open. Assume nothing you wrote in the chat has been read.

Put everything needed to decide into --summary: what you were doing, what you found, and what happens after each answer.
Never refer to the chat ("as shown above", "the error I mentioned", "option B from my last message"). Name things concretely: file paths, branch names, URLs, error text, numbers.
Give each non-obvious choice a --choice-description that states its consequence or trade-off, so the choice labels can stay short.
When the decision hinges on something visual, attach it with --media instead of describing it.

Bad: --summary "Which approach should I take?" --choice "A" --choice "B"

Good: --summary "The signup form (src/pages/Signup.tsx) fails validation on empty email. Fix by validating in the frontend or the API?" --choice "Frontend" --choice-description "Faster feedback in the form; API stays unchanged" --choice "API" --choice-description "One source of truth; every client gets the fix"

Immediate command response:

{"ok": true, "data": {"askId": "ask_abc123", "status": "scheduled"}}

When the user answers, Cockpit starts a new turn in the originating task with a compact, language-independent cockpit.ask.resolved JSON event. The original question is not repeated because it remains in the task context. The event includes answered_by showing who answered: "user" for the Ask window or PWA, a task ID for another Cockpit task answering via CLI, or "cli" for a task-external process such as a voice agent.

Free-form input produces:

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"type":"input","value":"Use blue"}]}

The user can attach supported images, text and source files, JSON, CSV, PDFs, audio, video, and office documents to any answer. Archives and executable formats are rejected. Attachments arrive as absolute paths in attachments with display name, MIME, size, and kind in attachment_metadata. File contents are never expanded into the event:

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"type":"input","value":"Review this report","attachments":["/tmp/agi-cockpit-uploads/5c1f.../upload_a1b2c3d4.pdf"],"attachment_metadata":[{"id":"upload_a1b2c3d4","path":"/tmp/agi-cockpit-uploads/5c1f.../upload_a1b2c3d4.pdf","name":"report.pdf","mime":"application/pdf","size":245760,"kind":"pdf"}]}]}

Single-question answers omit question_id. Multiple questions include it to preserve the correspondence between questions and answers. Answers use choice, choices, or input:

{"event":"cockpit.ask.resolved","version":1,"ask_id":"ask_abc123","outcome":"answered","answers":[{"question_id":"target","type":"choice","value":"staging"},{"question_id":"checks","type":"choices","values":["lint","tests"],"input":"typecheck"}]}

Closing the dialog without answering removes the Ask without sending a message to the agent or resuming the task. The task can still be resumed later with a regular user message.

cockpit ask requires a Cockpit task context so the later response always has one unambiguous destination. It is available for resumable agent tasks, not Terminal tasks, because Cockpit cannot safely restore a Terminal shell and deliver the continuation to the process that created the Ask.

Operating asks:

list, answer, and close operate Asks that other tasks created. They exist so an agent can act as the user's proxy — for example a voice agent relaying the user's spoken decision, or a coordinating task resolving a subtask's question it clearly has the context and authority to decide. Never answer an Ask just to clear it; when in doubt, leave it for the user.

cockpit ask list                                  # all open Asks with questions, choices, and media metadata
cockpit ask list --task task_3                    # only Asks from one task
cockpit ask answer ask_abc123 --choice "staging"  # answer a single-question Ask
cockpit ask answer ask_abc123 --choice-index 1    # same, by 1-based choice number
cockpit ask answer ask_abc123 --input "Use blue"  # free-form answer
cockpit ask answer ask_abc123 --question target --choice "staging" --question checks --choice "lint" --choice "tests" --input "typecheck"
cockpit ask close ask_abc123                      # close one Ask without answering
cockpit ask close --all                           # close every open Ask
cockpit ask close --task task_3                   # close all Asks from one task

answer resumes the originating task exactly like a user answer, with answered_by in the event. A task cannot answer its own Ask (the server rejects it); closing its own Ask is allowed.
Multi-question Asks must be answered in one command: prefix each answer group with --question <questionId> (ids come from list). Multi-select questions accept repeated --choice.
--choice must match the choice text exactly; use --choice-index (1-based, per list order) to avoid transcription mismatches. Mismatch errors return the valid choices.
Asks with media are asking for a visual judgment. Do not answer one unless the content has actually been checked — by the user looking at the Ask window, or by you if you can view the files. If it has not been checked, tell the user it is waiting on screen instead.
close never resumes the task; the asking task stays waiting until the user resumes it. Use it to clear stale Asks, not to skip questions that still need answers.
If the user answers on screen first, answer returns {"ok":false} with "Ask not found" — that is a race, not a failure; check cockpit ask list for what is still open.

Example uses:

Choose among multiple implementation approaches
Gather information that requires user judgment, such as a deployment target or branch name
Final confirmation before a destructive operation
Review screenshots, generated images, audio, or video