---
name: tangrid
description: Inspect and control macOS windows, displays, and desktops with the Tangrid CLI. Use for arranging windows in Flow or Snap mode, managing Flow tab groups, moving or focusing windows, changing window presentation, and observing layout changes.
---

# Tangrid CLI

Use the `tangrid` CLI to control the running Tangrid app. Treat live JSON responses as the source of truth for window identity, desktop topology, mode, capabilities, and observed outcomes. Use `--help` and `capabilities` to resolve syntax or availability for the installed version.

## Availability

TangridCLI requires macOS 14 or later and is included with Tangrid. Tangrid must be running for state queries and mutations; help and version work without it.

1. Check whether `tangrid` is on `PATH`.
2. If it is unavailable, check `/Applications/Tangrid.app/Contents/CLI/tangrid` and use that executable directly. Adjust the path if the app is installed elsewhere.
3. If the CLI cannot be found, explain that it ships with Tangrid. Users can install the command through **Tangrid Settings > Window Manager > CLI > Install CLI**.

Examples below use `tangrid`; substitute the full executable path when necessary.

## Observe, Select, Act, Verify

1. Read `tangrid state --json` for a coherent snapshot containing `sessionId`, `revision`, `mode`, `ready`, `busy`, windows, displays, desktops, and mode-specific layout. `tangrid status --json` is a lighter readiness check.
2. Resolve the requested windows and destination from that snapshot. Narrow queries with `windows`, `window`, `displays`, or `desktops` when needed. Use app bundle ID, title, and desktop context to distinguish windows. Clarify the target when available state cannot resolve an ambiguity.
3. Read `tangrid capabilities --json`, or `tangrid capabilities --window W --json`, when command availability or a window's restrictions matter. Inspect `available`, `unavailableReason`, and `requiredMode`.
4. Choose the smallest operation that accomplishes the request. Use supported `--dry-run` previews for broad arrangements or declarative layouts and inspect all affected windows. Where supported, pass the observed revision with `--if-revision TOKEN`.
5. Execute the requested change and inspect the returned state. Verify the relevant window, group, or layout if the result does not establish the requested outcome.

After reading the initial snapshot, plan the complete command sequence up front. For ordinary requests, execute the planned commands in one shell invocation to reduce round trips and user waiting. Preserve dependency order, run mutations sequentially, and stop on failure.

Split execution into additional planning rounds only when a complex request genuinely needs intermediate results to determine later commands, or an unexpected result requires replanning. Reuse returned post-operation state for verification when it establishes the outcome; avoid querying state again after every command.

Use `--json` for queries and mutations. Finite commands emit one response object on stdout, including structured failures. Watch emits one JSON object per line. Diagnostics use stderr.

## References and Selectors

In command syntax below, `W` is a window reference, `G` a Flow group reference, `D` a desktop reference, and `M` a display reference. Replace them with current values returned by queries.

- Window references such as `safari1` are stable only during the running Tangrid session. Restarting Tangrid resets window and group references; compare `sessionId` before reusing saved selections.
- Desktop references such as `desktop1` follow the current ordinary desktop ordering across displays. Adding, removing, or reordering desktops can change their meaning.
- Display references such as `studio-display` come from the connected inventory and can change after connection, disconnection, or renaming. Query again after topology changes.
- `focused` selects the focused window. `current` selects the focused window's desktop, falling back to the main display's active desktop unless a display is supplied. Both resolve once when a request begins.
- Multiple displays can each have an active desktop. Native fullscreen Spaces use separate `fullscreenN` references, returned by `desktops --include-fullscreen`; they are not ordinary layout destinations.
- Window lists are comma-separated references. Titles and display labels are not free-form reference expressions. Never manufacture references from app names or reuse illustrative IDs without querying.

Useful queries:

```sh
tangrid windows --desktop current --json
tangrid windows --app com.apple.Safari --json
tangrid windows --title-contains "README" --json
tangrid window W --json
tangrid displays --json
tangrid desktops --json
tangrid flow group list --json
```

Inventory includes observed floating, minimized, hidden, inactive-desktop, and inactive-tab windows. Their presence does not imply they can participate in an operation. Check readiness, presentation, placement, and capabilities. Unknown metadata is not evidence that a window or desktop is absent.

## Common Operations

| Intent | Command |
| --- | --- |
| Read or change app-wide mode | `mode [flow\|snap\|off]` |
| Focus a window or select a Flow tab | `focus W` |
| Focus a directional neighbor | `focus --from W --direction left\|right\|up\|down` |
| Move one window | `move W --desktop D` or `move W --display M` |
| Resize by configured steps | `resize W --direction grow\|shrink [--steps N]` |
| Fill the existing desktop's available area | `fill-screen W --enabled true\|false` |
| Enter or leave macOS native fullscreen | `fullscreen W --enabled true\|false` |
| Minimize or restore | `minimize W --enabled true\|false` |
| Request window closure | `close W` |

Prefix these commands with `tangrid` and add `--json`. Fill Screen and native fullscreen are distinct states; choose the one the user requested.

Keep the current mode unless changing it is part of the requested task. `mode flow`, `mode snap`, and `mode off` change a persistent app-wide preference. Mode-specific commands return `mode_mismatch` in the wrong mode and do not switch automatically.

`focus W` intentionally reveals the window: it restores minimization, unhides its app, selects its Flow tab, and activates its desktop as needed. Other commands do not implicitly make those presentation changes.

For move, choose either `--desktop` or `--display`. A display target means that display's current desktop. Add `--follow` when the task calls for activating the destination and focusing the moved window. Moving a window out of a Flow group moves only that member; use `flow group move` to move the whole group.

## Flow Layouts and Groups

Flow continuously manages tiled windows. `columns` means side by side; `rows` means top to bottom. Tangrid calculates positions and sizes.

```sh
tangrid flow layout --desktop D --json
tangrid flow arrange --windows W1,W2 --desktop D --style columns --json
tangrid flow tile --windows W1,W2 --json
tangrid flow float --windows W1,W2 --json
tangrid flow place --target W --relative-to G --side left --json
tangrid flow swap --first W --second G --json
tangrid flow balance --desktop D --json
tangrid flow rotate --desktop D --direction clockwise --json
tangrid flow flip --around G --json
tangrid flow orient --around G --orientation rows --json
```

For `place` and `swap`, targets can be windows or groups. A window target selects only that member, extracting it from a group if necessary. A group target preserves the entire group's identity, order, and active tab. A relative window inside a group identifies the group's shared region. Swap is limited to one desktop.

`arrange` gathers the selected windows onto the specified desktop, defaulting to the first selected window's desktop, and makes each an independent tiled window. Unselected windows retain their placement and group membership, but their geometry can change. Use `--desktop D --all-eligible` instead of `--windows` only when the request covers all eligible windows there.

```sh
tangrid flow group list --desktop D --json
tangrid flow group get G --json
tangrid flow group create --windows W1,W2 --active W1 --anchor W1 --json
tangrid flow group add G --windows W3,W4 --json
tangrid flow group remove G --windows W2 --placement tiled --json
tangrid flow group reorder G --windows W2,W1,W3 --json
tangrid flow group dissolve G --placement tiled --json
tangrid flow group move G --desktop D --json
```

Group creation requires at least two distinct manageable windows. Members from other desktops move to the first input window's desktop. Input order becomes tab order; active and anchor default to the first input window. Use the returned `result.groupId` for subsequent operations.

Adding members moves them to the existing group's desktop. Reorder requires the complete current member set without duplicates. Remove and dissolve default to independent tiled placement; `floating` is also supported. A group reference expires when the group dissolves or only one member remains. Use `focus W` to select a tab.

## Snap Layouts

Snap arranges windows once, then uses their current geometry and snapping participation for subsequent interactions. Tab groups require Flow mode.

```sh
tangrid snap layout --desktop D --json
tangrid snap arrange --windows W1,W2 --desktop D --style columns --json
tangrid snap place --window W1 --relative-to W2 --side right --json
tangrid snap place --window W --edge left --json
tangrid snap set-floating --windows W1,W2 --enabled true --json
```

The relative and edge forms of `snap place` are mutually exclusive; edge accepts `left` or `right`. Relative placement moves the source to the relative window's desktop and splits that window's region.

Snap arrange accepts the same explicit-window or desktop-scoped `--all-eligible` selection as Flow arrange. `snap set-floating` changes snapping exclusion while retaining current frames.

## Declarative Layouts

Use `flow apply` or `snap apply` for a complete desktop layout. Supply JSON through `--file FILE` or `--stdin`. The following IDs are illustrative; replace them with current references before use.

```json
{
  "apiVersion": 1,
  "desktopId": "desktop1",
  "unlisted": "error",
  "layout": {
    "type": "split",
    "orientation": "columns",
    "children": [
      { "type": "window", "windowId": "visual-studio-code1" },
      {
        "type": "tabbed",
        "windowIds": ["safari1", "safari2"],
        "activeWindowId": "safari1"
      }
    ]
  }
}
```

- `window` nodes contain `windowId`.
- `split` nodes have `orientation: columns|rows` and at least two children.
- `tabbed` nodes require at least two windows, cannot contain nested groups, and are available only in Flow.
- Each window may appear only once in the entire layout.

Apply gathers listed windows onto `desktopId` and replaces that desktop's participating layout. Default `unlisted: error` rejects omitted available tiled windows. Choose `unlisted: floating` only when floating omitted participating windows matches the request. Omitted existing floating windows retain their state.

Preview with `tangrid flow apply --file layout.json --dry-run --json`, then execute without `--dry-run`. For Snap, use `snap apply` and omit tabbed nodes. An optional input `ifRevision` must match `--if-revision` if both are supplied. A preview does not reserve state or guarantee later success.

## Preconditions and Outcomes

- Layout mutations require a normal desktop active on its display. Add supported `--activate-desktop` when activation is part of the requested operation. A dry run can validate an inactive desktop without activating it; unknown required layout state can still return `not_ready`.
- Moving a window into a Flow layout also requires an active destination. `move --follow` activates that destination and focuses the moved window.
- Explicitly selected minimized, app-hidden, native-fullscreen, or conflicting Fill Screen windows fail preflight unless the command itself requests the relevant presentation change. Resolve the reported conflict in line with the task rather than silently dropping windows.
- `--all-eligible` excludes unavailable and default-floating windows. Explicit lists validate every member before mutation.
- Native operations can fail after execution begins. Inspect `result.affectedWindowIds`, `completedWindowIds`, `failedWindowIds`, the operation record, and returned state. Additional windows may be affected by layout constraints.
- Successful mutations include `changed`, `beforeRevision`, `afterRevision`, `operation`, and post-operation state. `changed: false` is a successful no-op.
- Compare observed `frame` with allocated `layoutFrame` appropriately. Fill Screen, centered Flow presentation, and temporary minimization do not necessarily make a window floating. Geometry uses global logical points, origin at the main display's top left, positive right and down; negative coordinates are valid.

## Failures and Recovery

Read structured error `code`, `message`, mode context, and resource context even when the process exits unsuccessfully.

| Condition | Response |
| --- | --- |
| `app_not_running`, `not_ready`, `busy` | Check app status and readiness before continuing. |
| `mode_mismatch` | Inspect `currentMode` and `requiredMode`; change mode only when the task calls for it. |
| `stale_reference`, `revision_conflict`, missing window/desktop/group | Refresh state and resolve targets again before replanning. |
| `desktop_not_active`, `presentation_conflict`, `constraint_unsatisfied` | Inspect the relevant resource and capabilities; address the reported precondition. |
| `partial_failure` | Inspect completed and failed items and current state before attempting remaining work. |
| `timeout`, `disconnected` | Determine whether the mutation was accepted or completed before retrying. |

For mutations that may need recovery, provide a fresh UUID through supported `--request-id UUID` and retain it. After a transport failure, query `tangrid operation ID --json` or `tangrid operation --request-id UUID --json`. A client timeout does not mean the operation had no effect.

Tangrid deduplicates retained request IDs; reusing an ID with different arguments is rejected. Records remain while pending and for at least ten minutes after completion, and disappear when Tangrid restarts. An unknown or expired operation may already have executed. Refresh observed state and reconcile the outcome instead of blindly repeating a mutation.

Exit codes: `0` success including no-op; `1` app, transport, or execution failure; `2` invalid arguments; `3` state precondition failure; `4` partial execution.

## Watching Changes

Use `tangrid watch --events window,desktop,display,layout,group,mode --json` for requested ongoing observation; add `--desktop D` to scope it. Watch starts with a snapshot and cursor, checks state every 300 milliseconds, and can combine changes into one event.

Reconnection starts a fresh snapshot without replaying prior events. Stop the subscription once the requested condition is met or observation ends; use finite queries for ordinary one-time checks.
