Command line reference

Jiggle Mode includes the jigglemode command. With no command it opens the editor in your browser; the commands below do everything else, for people, scripts and AI agents. If you installed from the disk image, see Get started to make the command available in Terminal.

#The basics

jigglemode                 # open the editor in your browser
jigglemode --demo          # the same, with a pretend iPhone
jigglemode devices         # which phones are connected, and whether each is ready
jigglemode read            # show the Home Screen as text
jigglemode backups         # list backups, newest first
jigglemode restore --latest   # put back the layout from just before the last change

#Options for every command

Option	What it does
`--demo`	Use a pretend iPhone with made-up data. Nothing touches a real phone.
`--json`	Print JSON for programs instead of text for people.
`--device <UDID>`	Which iPhone or iPad, by UDID. Not needed when only one is connected.
`--no-open`	Don't open the browser when starting the editor.
`--port <PORT>`	Port for the editor (default: any free port).

#Making changes from the command line

Changes are described as a list of operations in a JSON file. plan checks them against the phone and saves a plan; apply writes it, with the same backup, check and put-back as the editor.

jigglemode plan ops.json --out plan.json
jigglemode apply plan.json

apply shows the changes and asks before writing. --yes skips the question; use it only in scripts you trust. With --json, or when no one is at the terminal, a write without --yes stops with exit code 2 and writes nothing.

An ops.json that makes a folder on page 2 and moves an app into the Dock:

json

[
  {"op": "create_folder", "name": "Travel", "items": ["com.example.flights", "com.example.hotels"], "at": {"in": "page", "page": 1}},
  {"op": "move", "item": "com.example.notes", "to": {"in": "dock", "index": 0}}
]

Pages and positions count from 0 (page 1 is "page": 0). Use ids exactly as jigglemode read --json gives them. The full list of operations is in the skill: jigglemode skill print references/ops.md.

#Every command

The help text below is copied from jigglemode itself (version 1.0.0-rc.1). Every command also takes --demo, --json and --device <UDID>.

#`jigglemode devices`

List connected iPhones and iPads and whether they are ready

List connected iPhones and iPads and whether they are ready

Usage: jigglemode devices [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode pair`

Ask your iPhone to trust this Mac (it shows "Trust This Computer?"). USB only

Ask your iPhone to trust this Mac (it shows "Trust This Computer?"). USB only

Usage: jigglemode pair [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode wifi`

Use your iPhone over Wi-Fi: set it up once over USB, check, allow changes, or forget it

Use your iPhone over Wi-Fi: set it up once over USB, check, allow changes, or forget it

Usage: jigglemode wifi [OPTIONS] <COMMAND>

Commands:
  setup    With the iPhone on a USB cable and unlocked: let this Mac reach it over Wi-Fi from now on. The phone already trusts this Mac, so it does not ask anything; it does start accepting this Mac's Wi-Fi key. The key is kept in your login Keychain
  status   Which phones are set up for Wi-Fi, whether each is on this network now, and whether changes over Wi-Fi are on
  changes  Allow or stop writing changes (apply, restore) over Wi-Fi when the cable is out. Off by default: reading over Wi-Fi works, changes over Wi-Fi are new and the cable is the tested route. Turning them on asks you to confirm in a terminal; programs and agents cannot turn them on
  forget   Delete this Mac's Wi-Fi key (from the Keychain) and record for a phone. The phone cannot be told to forget this Mac from here; the output says how to do that on the phone
  help     Print this message or the help of the given subcommand(s)

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode wifi setup`

With the iPhone on a USB cable and unlocked: let this Mac reach it over Wi-Fi from now on. The phone already trusts this Mac, so it does not ask anything; it does start accepting this Mac's Wi-Fi key. The key is kept in your login Keychain

With the iPhone on a USB cable and unlocked: let this Mac reach it over Wi-Fi from now on. The phone already trusts this Mac, so it does not ask anything; it does start accepting this Mac's Wi-Fi key. The key is kept in your login Keychain

Usage: jigglemode wifi setup [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode wifi status`

Which phones are set up for Wi-Fi, whether each is on this network now, and whether changes over Wi-Fi are on

Which phones are set up for Wi-Fi, whether each is on this network now, and whether changes over Wi-Fi are on

Usage: jigglemode wifi status [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode wifi changes`

Allow or stop writing changes (apply, restore) over Wi-Fi when the cable is out. Off by default: reading over Wi-Fi works, changes over Wi-Fi are new and the cable is the tested route. Turning them on asks you to confirm in a terminal; programs and agents cannot turn them on

Allow or stop writing changes (apply, restore) over Wi-Fi when the cable is out. Off by default: reading over Wi-Fi works, changes over Wi-Fi are new and the cable is the tested route. Turning them on asks you to confirm in a terminal; programs and agents cannot turn them on

Usage: jigglemode wifi changes [OPTIONS] <STATE>

Arguments:
  <STATE>  [possible values: on, off]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode wifi forget`

Delete this Mac's Wi-Fi key (from the Keychain) and record for a phone. The phone cannot be told to forget this Mac from here; the output says how to do that on the phone

Delete this Mac's Wi-Fi key (from the Keychain) and record for a phone. The phone cannot be told to forget this Mac from here; the output says how to do that on the phone

Usage: jigglemode wifi forget [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode read`

Read the Home Screen and show it. Changes nothing

Read the Home Screen and show it. Changes nothing

Usage: jigglemode read [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --out <FILE>     Also save everything that was read to this file, as JSON
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode plan`

Check a list of changes against the phone and show what they would do. Writes nothing

Check a list of changes against the phone and show what they would do. Writes nothing

Usage: jigglemode plan [OPTIONS] <OPS>

Arguments:
  <OPS>  A JSON file with the changes: a list of ops, or an object with an "ops" list

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --out <FILE>     Save the checked plan here, to write it later with `jigglemode apply`
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode apply`

Write a saved plan to the phone: backup first, check afterwards, undo if it did not land

Write a saved plan to the phone: backup first, check afterwards, undo if it did not land

Usage: jigglemode apply [OPTIONS] <PLAN>

Arguments:
  <PLAN>  A plan saved by `jigglemode plan --out`

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --yes            Do not ask before writing
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode backups`

List the backups taken before each change, newest first

List the backups taken before each change, newest first

Usage: jigglemode backups [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode restore`

Put a backup back on the phone, with the same checks as any change

Put a backup back on the phone, with the same checks as any change

Usage: jigglemode restore [OPTIONS] [BACKUP_ID]

Arguments:
  [BACKUP_ID]  Which backup (see `jigglemode backups`)

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --latest         Use the newest backup: the layout from just before the last change
      --json           Print JSON for programs instead of text for people
      --yes            Do not ask before writing
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode resolve`

After a write whose result is unknown, or whose undo could not be confirmed: read the phone, say which layout it shows, and allow writing again

After a write whose result is unknown, or whose undo could not be confirmed: read the phone, say which layout it shows, and allow writing again

Usage: jigglemode resolve [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode probe`

Save read-only diagnostics from a real phone into a folder. Never changes the phone

Save read-only diagnostics from a real phone into a folder. Never changes the phone

Usage: jigglemode probe [OPTIONS] --out <DIR>

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --out <DIR>      Folder for the results (created if missing)
      --json           Print JSON for programs instead of text for people
      --network        Use the Wi-Fi connection instead of USB
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
      --note <NOTE>    A note saved with the results, e.g. "locked, screen off" [default: ""]
  -h, --help           Print help

#`jigglemode mcp`

Run as an MCP server on stdin/stdout, for AI agents (Claude, Codex, Gemini, Cursor…). Reading is always allowed; writing to the phone only with --allow-apply

Run as an MCP server on stdin/stdout, for AI agents (Claude, Codex, Gemini, Cursor…). Reading is always allowed; writing to the phone only with --allow-apply

Usage: jigglemode mcp [OPTIONS]

Options:
      --allow-apply
          Let agents write changes to the phone. You confirm every write yourself: in the agent's app when it can ask you, otherwise in a Jiggle Mode dialog on this Mac (Cancel, or no answer within 60 seconds, means no). If neither is possible, nothing is written. Setting the environment variable JIGGLEMODE_ALLOW_APPLY=1 does the same
      --demo
          Use a pretend iPhone with made-up data. Nothing touches a real phone
      --allow-apply-without-confirmation
          At your own risk: let agents write changes to the phone with no confirmation from you at all; the agent's own word is enough. Only for a fully unattended agent you trust. Each write is still checked, backed up, read back and put back if it did not land
      --json
          Print JSON for programs instead of text for people
      --device <UDID>
          Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help
          Print help

#`jigglemode skill`

Install or show the Jiggle Mode Agent Skill, which teaches agents to use Jiggle Mode

Install or show the Jiggle Mode Agent Skill, which teaches agents to use Jiggle Mode

Usage: jigglemode skill [OPTIONS] <COMMAND>

Commands:
  install  Install the skill to ~/.claude/skills/jigglemode and ~/.agents/skills/jigglemode (or to <DIR>/jigglemode for each --dir). Never overwrites a copy you edited unless --force
  path     Show where the skill is installed and whether each copy is current
  print    Print one of the skill's files (default SKILL.md); --list names them
  help     Print this message or the help of the given subcommand(s)

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode skill install`

Install the skill to ~/.claude/skills/jigglemode and ~/.agents/skills/jigglemode (or to <DIR>/jigglemode for each --dir). Never overwrites a copy you edited unless --force

Install the skill to ~/.claude/skills/jigglemode and ~/.agents/skills/jigglemode (or to <DIR>/jigglemode for each --dir). Never overwrites a copy you edited unless --force

Usage: jigglemode skill install [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --dir <DIR>      A skills folder to install into instead, e.g. .agents/skills in a project. Repeatable
      --force          Overwrite copies that were edited
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode skill path`

Show where the skill is installed and whether each copy is current

Show where the skill is installed and whether each copy is current

Usage: jigglemode skill path [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --dir <DIR>      Skills folders to check instead of the usual two. Repeatable
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode skill print`

Print one of the skill's files (default SKILL.md); --list names them

Print one of the skill's files (default SKILL.md); --list names them

Usage: jigglemode skill print [OPTIONS] [FILE]

Arguments:
  [FILE]  A file inside the skill, e.g. references/ops.md

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --list           List the files instead
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#`jigglemode licenses`

Print the licenses of the open-source components Jiggle Mode includes

Print the licenses of the open-source components Jiggle Mode includes

Usage: jigglemode licenses [OPTIONS]

Options:
      --demo           Use a pretend iPhone with made-up data. Nothing touches a real phone
      --json           Print JSON for programs instead of text for people
      --device <UDID>  Which iPhone or iPad, by UDID. Not needed when only one is connected
  -h, --help           Print help

#Exit codes

Each exit code means one thing, so scripts and agents can act on it.

Code	Meaning
`0`	Done: the phone shows the new layout, or there was nothing to change
`1`	Something else went wrong, or you answered no (see the message)
`2`	The command was used wrongly (bad arguments, a file that cannot be read, no such backup), or it needs your yes: run it in a terminal, or add --yes
`3`	The changes break Home Screen rules or cannot be made; nothing was written
`4`	The phone changed since the plan was made; read it again and redo the plan
`5`	No phone found, not trusted, locked, or not answering
`6`	The phone ignored the write (a locked phone is expected to); nothing to undo
`7`	The phone ended up wrong, so the old layout was put back and checked
`8`	The phone ended up wrong, and putting the old layout back was not confirmed
`9`	The result of a write is unknown; run `jigglemode resolve` before writing again 10 The phone is reachable only over Wi-Fi and changes over Wi-Fi are off: plug in the cable, or run `jigglemode wifi changes on`. Nothing was sent

#MCP tools

What jigglemode mcp offers an AI agent. Only the ones marked Yes can change the phone, and only when writing is allowed and you confirm.

Tool	Changes the phone?	What it does
`list_devices`	No	Lists the iPhones and iPads this Mac can reach (USB or Wi-Fi) with their status: ready, locked, untrusted (the phone does not trust this Mac yet: call pair_device), trust_pending (waiting for the person to tap Trust), or error, and what the person should do for each.
`read_layout`	No	Reads the Home Screen of the phone and returns it compactly: the Dock and each page with every item's id, name and kind (apps, folders with their contents, widgets and stacks with sizes, web clips), free cells per page, the grid size, the App Library count, warnings, and the fingerprint to pass to plan_changes.
`plan_changes`	No	Checks a list of edits (ops) against the phone's current layout and returns: whether they can be written, rule errors and warnings in plain words (e.g.
`preview_layout`	No	Draws the Home Screen as a PNG image (pages, widgets, folders, Dock; changed items ringed in yellow) plus a row-by-row text grid, so you or the person can see it.
`apply_plan`	Yes	Writes a plan from plan_changes to the real iPhone or iPad.
`list_backups`	No	Lists the backups Jiggle Mode saved before each write to this phone (each is the layout the phone showed just before a write), newest first, with when and why each was made, and undo_backup_id: the one that undoes the last write.
`restore_backup`	Yes	Writes a backup from list_backups back to the real iPhone or iPad, with the same safety steps as apply_plan (a new backup first, read back, roll back if it did not land).
`write_status`	No	Reports the write running now or the last one made through this server to this phone: its steps so far, and when finished, its full outcome.
`resolve_unknown_write`	No (clears a record on the Mac)	After a write ended "unknown" or "rollback_failed", or a write was refused because an earlier one is unfinished: reads the phone, says whether it shows the layout from before that write, the planned one, or something else, and clears the record that blocks further writes.
`pair_device`	No (asks the phone to trust this Mac)	For a device list_devices shows as untrusted: asks it to trust this Mac (“Trust This Computer?”), over a USB cable, and says what the person must do on the phone: unlock it, tap Trust, enter their passcode.

Command line reference

#The basics

#Options for every command

#Making changes from the command line

#Every command

#jigglemode devices

#jigglemode pair

#jigglemode wifi

#jigglemode wifi setup

#jigglemode wifi status

#jigglemode wifi changes

#jigglemode wifi forget

#jigglemode read

#jigglemode plan

#jigglemode apply

#jigglemode backups

#jigglemode restore

#jigglemode resolve

#jigglemode probe

#jigglemode mcp

#jigglemode skill

#jigglemode skill install

#jigglemode skill path

#jigglemode skill print

#jigglemode licenses