---
canonical: "https://agi-labo.com/en/tools/cockpit/docs/cockpit-cli/reference/secret"
title: "Secure input"
description: "Generated reference for Secure input, including its syntax, options, results, and constraints from the canonical cockpit CLI source."
section: "Reference"
order: 109
pageType: reference
lastVerifiedVersion: 4.61.0
lastVerifiedAt: "2026-08-27"
draft: false
surfaces:
  - cli
operatingSystems:
  - windows
  - macos
  - linux
plans:
  - guest
  - member
navigation: false
---

This reference is generated from the same canonical source distributed as cockpit CLI help. See [Cockpit CLI](/en/tools/cockpit/docs/cockpit-cli) for concepts and safe operating guidance.

`cockpit secret` requests a single use of a secret in a fixed browser password field. It is separate from Ask: the value never becomes an Ask answer, chat message, queued message, CLI result, diagnostic event, or persisted task state.

```bash
cockpit secret request --label "Cloudflare password" --summary "Fill the password field on this login page" --to browser --tab <tabId> --selector 'input[type="password"]' --expires-in 10m
cockpit secret status <requestId>
cockpit secret cancel <requestId>
```

All three commands require the authenticated requesting task's local CLI context. The task's secret capability is checked independently of the general CLI token; knowing a request ID or choosing another task ID grants no access. The CLI can use the local file IPC bridge for metadata if loopback is blocked before connection; the input value never uses that bridge. A request is never retried after a connection was established. Remote-target CLI calls are unsupported; use the PWA on the requesting PC's HTTPS connection to enter the value. There is no secret value argument, stdin value, `get`, `reveal`, arbitrary shell injection, or Vault.

`request` returns immediately with `id`, `status`, and `expiresAt`. `status` and `cancel` return the same metadata and a value-free `result` when available. Every response carries `instance` (`production`, `dev`, or `dev-task-<hash>`) like other commands, so a request sent to the wrong Cockpit instance is visible. The default expiry is ten minutes from creation. `--expires-in` accepts whole seconds (`30s`) or minutes (`5m`), up to ten minutes. Single use is always enforced; `--once` is unnecessary. Labels and summaries describe the purpose, and must not contain credentials.

A request appears where Asks do: on the desktop in its own small window (like an Ask window, controlled by `notifications.askWindow`) and in the side panel Ask tab (`cockpit side-panel ask`), and in the PWA Inbox next to Asks and displays. It plays the Ask chime (`notifications.askSound`), shows the default `medium` priority badge, and is ordered with Asks. Because the window is separate from the main window, the in-app browser never covers it; hiding the window keeps the request in the Ask tab. Only the presentation is shared: a secure input request is not an Ask. It never appears in `cockpit ask list`, cannot be answered with `cockpit ask answer`, is never sent to Discord or Slack, never fires `ask.*` Hooks, never produces `cockpit.ask.resolved`, and accepts no attachments.

Each request shows the requesting PC, task, purpose, Browser Identity, actual page URL/origin, main frame, selector, and deadline before accepting a masked input. Submit with **Fill this field once** (日本語: **この入力欄に一度だけ入力**). Only a unique, visible, enabled password input in the main frame can be used, on HTTPS or loopback HTTP. The original document and element are bound at creation; navigation, replacement, permissions changes, or an ambiguous selector fail closed. No alternative field is chosen. Form submission and login-button clicks are never automatic.

PWA input requires authenticated WSS over HTTPS. An unencrypted connection cannot submit or cancel, and never falls back automatically. Desktop input uses trusted IPC from the main window or the request's own window. Both use the same server-side single-use state machine. Simultaneous submissions consume the permission only once and synchronize the authoritative state to all clients; draft values are cleared when a request leaves the waiting state or the client disconnects, closes, or hides the input.

States: `pending` (waiting), `delivering` (sending once), `completed` (input completed), `expired`, `canceled`, `failed` (destination unavailable), and `unconfirmed` (delivery result unknown). A lost acknowledgement never causes automatic retry. Reconnect to check status; do not resend an unconfirmed delivery. Cancel affects only a pending request, and cannot undo input that has started. Result notifications sent to the requesting task contain only the request ID, status, and result, including when that task is busy. Notifications preserve the task’s model, effort, and approval mode. Settled request metadata is available to `status` for one minute, with at most 100 settled requests retained in memory. After removal, `status` returns `secret_request_unavailable`; removal never permits another delivery. A request leaves every desktop and PWA surface as soon as it is no longer `pending` or `delivering`; nothing stays on screen to show the result or an empty count. Read the result with `cockpit secret status` or the `cockpit.secret.result` notification.

## Errors

A failure prints `{"ok":false,"code":"...","error":"...","instance":"..."}` and exits with status 1. Branch on `code`; `error` is a fixed description. No error contains an input value or page content. A failed `request` creates no request, except `secret_outcome_unknown`, whose outcome is unknown. A restored tab that is not loaded yet is loaded first, as with other browser commands.

| `code` | Meaning and recovery |
| --- | --- |
| `invalid_secret_command` | Use `request`, `status`, or `cancel`. |
| `invalid_secret_options` | A missing, repeated, unknown, or out-of-range option (for example `--expires-in` above `10m`, a label over 200 characters, or a summary over 2000). |
| `invalid_request_id` | The argument is not a request ID. |
| `authenticated_task_required` | Run the command from the requesting task launched by AGI Cockpit while it is still running. |
| `secret_request_unavailable` | The request ID does not exist, belongs to another task, or passed its one-minute retention. |
| `secret_request_limit` | 100 requests are already waiting; settle or cancel some first. |
| `secret_request_expired` | The deadline passed while the destination was being prepared; request again with a longer `--expires-in`. |
| `tab_not_found` | The tab does not exist or was closed; open the page again. |
| `tab_not_owned` | The tab belongs to another task; open the page in a tab of this task. |
| `browser_access_denied` | The tab's Browser Identity is no longer assigned to this task. |
| `insecure_origin` | The page is neither HTTPS nor loopback HTTP (`localhost`, `127.0.0.1`, `[::1]`). |
| `invalid_selector` | `--selector` is not a valid CSS selector. |
| `element_not_found` | The selector matches nothing in the main frame. |
| `ambiguous_selector` | The selector matches more than one element; make it unique. |
| `not_main_frame` | The selector matches only inside an iframe; only the main frame can be used. |
| `invalid_target_field` | The element is not a password input, or is hidden, disabled, or read-only. |
| `destination_changed` | The page navigated or the tab was replaced while the request was being prepared; check the page and request again. |
| `destination_unavailable` | The tab did not finish loading, its renderer crashed or stopped responding, or preparation failed for another reason. Check the tab (`cockpit browser tabs` health, `tab recreate`) and request again. |
| `cockpit_unreachable` | AGI Cockpit could not be reached and nothing was sent. |
| `secret_outcome_unknown` | The connection was lost after the command was sent. A `request` may have been created and is shown to the user; do not resend automatically. |

`host_not_supported` (with `--host`) and, on Windows, `node_runtime_unavailable` / `node_runtime_failed` are reported by the launcher before the command runs.

Delivery values stay in transient memory, never on disk, in PWA storage/cache, or in Ask forwarding. Requests are not restored after restart, and values are never restored or resent. Task completion, deletion, expiry, cancellation, and delivery completion/failure release delivery copies. This consumes Cockpit's permission to deliver once; it does not guarantee external exactly-once execution or complete erasure of all memory.

The destination site can retain the field value and tools that read its DOM or evaluate scripts may read it after input. The feature does not promise that AI cannot read destination data. It assumes trusted PC/PWA/destination devices; it is not isolation from a compromised device. Discarding Cockpit's delivery copy does not clear the destination field.