cockpit display

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 display [--text <text>|--html <html>|--file <path>|--stdin] [--title <title>] [--directory <path>] [--width <px>] Usage: cockpit display list [--task <taskId>] Usage: cockpit display close <displayId>

Put a frontmost display-only message in front of the user. It never waits for a reply — use it for reminders, progress notices, or lightweight status screens. A Display carries the task it was sent from, so the user can jump to that task from the desktop window and from the PWA.

cockpit display --text "Stretch break in 2 minutes" --title "Reminder"
cockpit display --html "<main><h1>Standup</h1><p>Starts at 10:00.</p></main>" --title "Reminder" --width 760
cockpit display --file reminder.html --title "Reminder" --width 900
cat reminder.html | cockpit display --stdin --title "Reminder" --width 900
cockpit display list
cockpit display close 2f6c1a0b9d4e5f70

Options:

• --text <text> — show a frontmost text display (--summary is an alias)
• --html <html> — show a frontmost HTML display
• --file <path> — show a frontmost HTML display from a file
• --stdin — read HTML from stdin
• --title <title> — override the display title
• --directory <path> — override the display directory
• --width <px> — set the display window width when the HTML layout needs more horizontal room

list and close are subcommands, so cockpit display list never creates a notice reading "list". Pass --text list to show that word.

Creating

Creation answers {"ok":true,"data":{"id":"<displayId>","duplicate":false,"state":"pending"}}. Keep the id: it is the argument cockpit display close takes.

Duplicate suppression

Cockpit suppresses repeats on the receiving side, so retries and concurrent sends never stack up windows or PWA entries.

• Comparison key: originating task ID, display kind (text or html), title, and body. All four must match exactly. --width and --directory are presentation only and are not part of the key.
• The key compares the notice exactly as it is stored and shown, so it matches what the user sees. --title and a --text body are stored with leading and trailing whitespace stripped, so --text "Standup" and --text "Standup " are the same notice. An HTML body is stored verbatim and compared byte for byte, so one differing byte anywhere in the markup makes a different notice; two HTML notices are never merged just because they look alike.
• Notices sent from outside any task share the single origin scope external. Notices from two different tasks are never merged, even when their text is identical.
• While a matching Display is still open, a repeat reuses it: no second window, no second PWA entry, and no re-raise to the front. The answer is {"ok":true,"data":{"id":"<existing id>","duplicate":true,"state":"pending"}}.
• For 10 seconds after a matching Display is closed, a repeat is still treated as the same notice and answers {"ok":true,"data":{"id":"<closed id>","duplicate":true,"state":"closed"}}. This absorbs a retry that races with the user closing the window.
• After those 10 seconds, the same content is shown again as a new Display, so a legitimate recurring notice is never lost.
• Suppression is never an error and never a non-zero exit. Treat duplicate: true as success and do not retry.

Listing and closing

cockpit display list answers {"ok":true,"data":{"displays":[{"id","taskId","kind","title","directory","createdAt"}]}} for every open Display, newest state included. --task <taskId> keeps only the Displays from that task. taskId is null for a notice created outside a task.

cockpit display close <displayId> closes exactly that Display and nothing else. It closes the desktop window and removes the entry from the PWA list. It never sends an answer to an agent and never resumes a task.

• Success: {"ok":true,"data":{"id":"<displayId>","state":"closed"}}, exit 0.
• Already closed (by the user, by another CLI call, or by the window being closed): {"ok":false,"error":"Display already closed","code":"display_already_closed"}, exit 1. Closing twice is reported, not retried.
• Unknown ID: {"ok":false,"error":"Display not found","code":"display_not_found"}, exit 1. Cockpit remembers closed Display IDs for 10 minutes; a Display closed longer ago than that also answers display_not_found.

HTML displays open http and https links in the system browser without navigating the display window. Other URL schemes are ignored.