---
canonical: "https://agi-labo.com/tools/cockpit/docs/cockpit-cli/reference/app"
title: "cockpit app"
description: "cockpit appの構文、オプション、結果、制約をcockpit CLIの正本から自動生成したリファレンスです。"
section: "リファレンス"
order: 106
pageType: reference
lastVerifiedVersion: 4.61.0
lastVerifiedAt: "2026-08-27"
draft: false
surfaces:
  - cli
operatingSystems:
  - windows
  - macos
  - linux
plans:
  - guest
  - member
navigation: false
---

このReference本文は、アプリが配布するcockpit CLIヘルプと同じ英語の正本から自動生成されています。日本語の概念説明と安全な使い方は[cockpit CLI](/tools/cockpit/docs/cockpit-cli)を参照してください。

Attach an existing Android emulator, Android physical device, or booted iOS Simulator to the current task as an App Surface. Cockpit mirrors the whole screen, exposes a semantic accessibility snapshot, and supports screenshot coordinates when a control has no semantic element. It does not boot, shut down, install, launch, or terminate a target or wrap Expo, Flutter, Gradle, Metro, or Xcode.

One target can belong to only one task. Completing or deleting that task detaches the target without stopping the app. The first attachment to an Android physical device requires an interactive Cockpit Ask; after requesting approval, stop and wait for the user response. Emulators and Simulators do not require approval.

## Targets and lifecycle

```bash
cockpit app doctor
cockpit app targets
cockpit app attach <target-id>
cockpit app status
cockpit app show
cockpit app hide
cockpit app detach
```

`doctor` checks ADB/Xcode availability, bundled control-runtime integrity, online targets, and the current attachment. It also returns `diagnosticReport` metadata for the newest local Node diagnostic report, when one exists, so a fatal main-process failure can be correlated before exporting diagnostics. It returns machine-readable `pass`, `warn`, or `fail` checks with a `nextAction` when recovery requires an external command. `targets` reports the platform, emulator/Simulator/physical-device kind, transport, online/offline/unauthorized state, capabilities, the owning task when busy, and duplicate aliases for the same Android physical device. An Android target ID is its ADB serial; an iOS Simulator target ID is its `simctl` UDID. Only booted iOS Simulators are online.

`attach` performs an initial runtime and accessibility observation before returning. `status` includes the resulting `health`: target, mirror, accessibility, input, keyboard, foreground app, the last structured error, and whether the surface is operable. `show` and `hide` affect only the App Surface panel; mirroring and attachment continue while hidden. `detach` preserves the last frame as stale and never terminates the target app.

Outside a Cockpit task, pass `--task-id <id>` to task-scoped commands. `targets` and the platform-readiness portion of `doctor` work without it.

## Observe

```bash
cockpit app snapshot
cockpit app screenshot --output ./artifacts/app.png
cockpit app wait --text "Welcome" --timeout 10000
cockpit app wait --not-text "Developer Menu" --stable-ms 500 --require
cockpit app wait --any-text "Home" --any-text "Sign in" --none-text "Loading"
cockpit app wait --label "Continue" --role button
cockpit app wait --label "Mission Notes" --role textbox --label-match prefix
cockpit app wait --ref @e2 --timeout 5000
cockpit app wait --status attached --timeout 10000
cockpit app wait --package host.exp.exponent --keyboard hidden
```

`snapshot` returns fresh opaque references such as `@e1`, an `accessibility` health object, and optional recovery warnings. Android retries a temporarily empty tree. A valid but still empty tree returns `degraded: true` and `accessibility.state: "empty"` with `empty_accessibility_tree`; a broken or unavailable tree fails with `accessibility_unavailable` instead of reporting an unsafe empty success.

Any tap, fill, swipe, or key action invalidates opaque references; take another snapshot before reusing them. `screenshot` returns a PNG data URL unless `--output` or `--out` is supplied. Its viewport states `coordinateSpace` and `screenshotScale`.

`wait` can combine positive text, negative text, repeated `--any-text` and `--none-text`, semantic element, attachment status, foreground Android package, keyboard state, and `--stable-ms`. It returns `matched`, `timedOut`, and `elapsedMs`. A normal timeout is a successful result with `timedOut: true`; add `--require` to make timeout fail with `condition_not_met`. Negative text conditions only match against a healthy non-empty accessibility tree, preventing a missing snapshot from becoming a false pass.

## Operate

```bash
cockpit app tap @e2
cockpit app tap --label "Begin Investigation" --role button
cockpit app tap --label "Account" --role button --label-match prefix
cockpit app tap --label "Continue" --expect-text "Case Files" --timeout 10000
cockpit app tap --x 540 --y 1200
cockpit app fill @e3 "こんにちは"
cockpit app fill --label "Mission Notes" --role textbox $'東京 🗼\nSecond line'
cockpit app fill --label "Mission Notes" --role textbox --label-match prefix $'東京 🗼\nSecond line'
cockpit app swipe up
cockpit app swipe --direction left
cockpit app swipe --x1 540 --y1 1800 --x2 540 --y2 600
cockpit app press back
cockpit app press home
cockpit app press enter
cockpit app keyboard status
cockpit app keyboard hide
```

Prefer `--label` with an optional `--role`, then opaque references when already working from a fresh snapshot, then screenshot coordinates when accessibility does not expose a control. Labels use case-sensitive `exact` matching by default. Add `--label-match prefix` or `--label-match contains` only when a platform appends accessibility context such as a placeholder. Matching never silently becomes fuzzy; zero matches fail with `element_not_found`, while multiple matches fail with `ambiguous_element` and return their refs. Action results include the requested label and match mode alongside the resolved target.

Android coordinates are screen pixels and map directly to screenshot pixels. iOS Simulator action coordinates are logical screen points; multiply by `screenshotScale` to locate the same point in the PNG. Every action response has an `actionId`, backend, resolved semantic target when used, final point and coordinate space when applicable, and `dispatched: true`. Dispatched means the platform accepted the input, not that the app reacted. Use `--expect-text` or `--expect-not-text` on tap, swipe, and press to require an observable postcondition; unmet postconditions fail with `condition_not_met` and include both the dispatched action and wait result.

`fill` replaces the selected field through a UTF-8-safe path. Android first uses the active scrcpy control channel and falls back to supported clipboard, ADB keyboard, or IME-compatible paths. Cockpit then reads a fresh accessibility snapshot and requires the exact field value, including Unicode and newlines. A dispatched value that cannot be confirmed fails with `input_not_verified` and never becomes a silent success. Secure fields are masked in snapshots and reject `fill` with `secure_field`. `keyboard hide` dismisses the software keyboard and verifies it is hidden; unverifiable or unsuccessful dismissal fails with `keyboard_not_hidden`. On iOS, `press back` performs the standard left-edge back gesture.

## Result and error contracts

All commands print one JSON object. Success:

```json
{"ok":true,"data":{"status":"attached"}}
```

Failure:

```json
{"ok":false,"code":"target_busy","error":"Pixel is attached to task task-123","data":{"attachedByTaskId":"task-123"}}
```

Stable App Surface error codes are:

- `not_attached`
- `target_busy`
- `target_offline`
- `stale_ref`
- `ambiguous_target`
- `element_not_found`
- `ambiguous_element`
- `accessibility_unavailable`
- `unsupported_capability`
- `input_not_verified`
- `condition_not_met`
- `keyboard_not_hidden`
- `secure_field`
- `approval_required`
- `app_error`

An `offline` or `stale` surface keeps the last frame visible but disables interaction. Treat a returned error as the boundary: do not retry physical approval, bypass secure input, steal a busy target, or start/stop an app unless the user separately asks for that action.

## Target readiness

For iOS Simulator, install Xcode and boot the intended Simulator before discovery:

```bash
xcrun simctl list devices
xcrun simctl boot <udid>
```

Use the platform's own tools to install and launch the app. Cockpit reports a shut-down Simulator as `offline` and never boots it automatically.

Before attaching a USB or Wi-Fi device, ensure Android debugging is enabled and `cockpit app doctor` reports ADB plus the intended target. `unauthorized` means the user must accept Android's debugging prompt on the device. A Wi-Fi and USB entry with duplicate aliases represents the same device; choose one transport rather than attaching both.

For an end-to-end check, run `doctor`, attach the target, verify `status.health`, take a snapshot and screenshot, use a label action with a postcondition, fill a non-secret field with exact Unicode text, hide the keyboard, swipe, press Back, hide/show the panel, then detach. Confirm the app process remains running throughout. If a failure contains an `actionId`, preserve it with the raw JSON and nearest screenshot so the action, frame, snapshot, and recovery path can be correlated.