> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryscrolly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# scrollyctl

> Reference for scrollyctl, the command you or your AI agent run in Terminal on the Mac to link it, check setup and install the setup skill.

`scrollyctl` is installed on your Mac by the Scrolly Installer. You run it in Terminal, or your AI agent runs it for you. It links the Mac to your organization, reports what is left to set up, does the few setup steps that are commands, and installs the [setup skill](https://docs.tryscrolly.com/agents/setup-skill.md).

```text theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl <command> [options]
```

Run `scrollyctl --help` or `scrollyctl <command> --help` to see the built-in help.

| Command | What it does |
| - | - |
| [`enroll`](#enroll) | Links this Mac with a pairing code from the console. |
| [`link`](#link) | Links this Mac by approving it in your browser, with no code to type. |
| [`open`](#open) | What the Scrolly Mac app runs: links the Mac, or opens the console. |
| [`setup status`](#setup-status) | Shows what is done and what remains for this Mac and each phone. |
| [`setup <step>`](#setup-step) | Does one setup step, or re-reads it after you did it. |
| [`skill install`](#skill-install) | Installs the setup skill for your AI agent. |
| `status [--json]` | Shows this Mac's version, link, connection and service status. |
| `restart` | Restarts Scrolly's background services on this Mac. |
| `unlink` | Forgets the Mac's local link and tries to revoke it in the console. If the Mac was offline, an Admin can finish from [Macs](https://docs.tryscrolly.com/guides/phones.md#unlink-a-mac). |
| [`wda team`](#wda-team) | Stores this Mac's Apple Developer team ID, so the Mac builds WebDriverAgent by itself. |
| [`wda setup`](#wda-setup) | Builds and installs WebDriverAgent for a phone by hand on a supported iPhone. |

## How it works

`scrollyctl setup` does not work anything out itself. It asks the Scrolly provider running on the same Mac, over a private Unix socket, for the setup report. The console also uses that report, with confirmations you make in the browser.

* The socket is readable only by your own macOS user. Its folder is private to you, and the provider checks who is connecting before it reads a request.
* It is a file on this Mac, never a network port. `scrollyctl setup` cannot read another Mac's status.
* The one action it can ask a phone to take is requesting add-only Photos access (see [`setup <step>`](#setup-step)). It cannot tap, type, open a session or read a credential.
* `scrollyctl` never asks for a password and never passes one on. The one step that needs your Mac password runs `sudo` in your own Terminal window, and `sudo` asks you there.

Nothing `scrollyctl` prints holds a token, a credential or a password.

> [!NOTE]
>
> Credentials are written to a private folder, `~/Library/Application Support/Scrolly` by default, with files that only you can read. Do not open or edit them. They are the Mac's identity.

## enroll

Links this Mac to your organization with a one-time pairing code.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl enroll <code>
```

An organization Admin creates the code in the console under **Add a Mac**. It looks like `7KQ2M-X9D4F`, works once and expires after ten minutes. `enroll` sends the code to Scrolly, receives this Mac's credentials, writes them to a private folder and restarts the Scrolly background services so they pick the credentials up.

**code** `string` *required*

The pairing code from the console.

**--name** `string`

What to call this Mac in the console. Defaults to the Mac's computer name.

**--new** `flag`

Add this Mac as a new Mac even if it is already linked. Without it, a Mac that is already linked is enrolled again in place, and the credentials it held stop working.

**--coordinator** `string`

The Scrolly address to enroll with. It must start with `https://` (plain `http://` is accepted only for this Mac itself). Defaults to the address this Mac already uses, then to the one your installer was built for. You do not normally need it.

**--dir** `path`

Where the Mac's configuration and credentials live. Defaults to `~/Library/Application Support/Scrolly`. You do not normally need it.

**--json** `flag`

Print the result as JSON for an AI agent. It never contains a secret.

**--no-restart** `flag`

Do not restart the Scrolly background services afterwards.

On success `enroll` prints something like:

```text theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
Enrolled as Studio Mac (mac-7kq2mx9d4fab).
Reachable at https://mac-7kq2mx9d4fab.providers.example.com.
Credentials are in /Users/you/Library/Application Support/Scrolly, readable only by you.
```

When the Mac was already linked it says `Enrolled again`. With `--json` it prints these fields:

**providerId** `string`

The Mac's ID.

**name** `string`

The Mac's name in the console.

**publicBaseUrl** `string`

The address the console uses to reach this Mac.

**reenrolled** `boolean`

`true` when an existing link was replaced in place.

**relay** `boolean`

Whether remote access to this Mac is set up.

**configDir** `string`

The folder holding the credentials.

### Failures

`enroll` checks everything it can before it spends the code: that the folder is writable and that the Mac's configuration would load. If something fails earlier, nothing is spent and nothing is written. A refused code prints the reason and exits with status 1. Every refused code reads the same, whether it is wrong, expired or already used.

> [!WARNING]
>
> If Scrolly accepts the code but this Mac cannot install what it sent, the code is spent. `enroll` tells you so. Create a new code in the console and run it again.

## link

Links this Mac by approving it in your browser, with no code to type.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl link
```

`link` prints a short code and a page address, and opens the page in your browser. Sign in, check that the page shows the same code, and approve it. You must be an Admin of the organization. `link` waits, then writes the same credentials `enroll` writes. The code expires if it is not approved in time, and an Admin can turn the Mac down.

**--name** `string`

What to call this Mac. Defaults to its computer name.

**--new** `flag`

Add this Mac as a new one even if it is already linked.

**--no-browser** `flag`

Print the page address instead of opening your browser. You can open it on another computer and enter the code there.

**--gui** `flag`

Show the code and the result in dialogs instead of Terminal text.

**--events** `flag`

Print one JSON object per line, for the Scrolly Mac app's window.

**--coordinator** `string`

As for `enroll`.

**--dir** `path`

As for `enroll`.

**--no-restart** `flag`

Do not restart the Scrolly background services afterwards.

## open

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl open
```

This is what the Scrolly Mac app runs when you open it. On an unlinked Mac it starts linking, in dialogs. On a linked Mac it offers to open the console or to link the Mac again. You rarely need to run it yourself. It accepts `--coordinator`, `--dir` and `--events` (print the Mac's state as one JSON line, for the app's window).

## setup status

Shows what the Mac knows about its setup and attached phones.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl setup status [--json] [--recheck]
```

**--json** `flag`

Print the versioned [setup report](#the-setup-report) as JSON, for an AI agent.

**--recheck** `flag`

Have the Mac read its sleep setting and each phone's apps again before reporting, instead of reporting what it last read.

**--dir** `path`

Where the Mac's configuration lives. Defaults to this Mac's.

Without `--json` it prints a readable checklist. `[x]` is done, `[ ]` is pending with the reason, and `[?]` is unknown. Unknown means the step has not been read yet. It is never a pass.

```text theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
Studio Mac (mac-7kq2mx9d4fab) — connected to the coordinator

This Mac (runs 1 phone)
  [ ] Mac set never to sleep — This Mac sleeps after 10 minutes idle, which drops every phone on it

No phone is plugged into this Mac yet.

Not ready yet. Next: Mac set never to sleep. Run `scrollyctl setup mac_never_sleeps` in your own Terminal.
```

The example is shortened. The real output lists every step. When setup is finished the last line reads `Ready to schedule.`

## setup step

Does one step, or re-reads it once you have done it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl setup <step> [--device <phone ID>] [--json]
```

`<step>` is a step name from `setup status`, such as `mac_never_sleeps` or `developer_mode`. Names are not case sensitive, and `-` works in place of `_`.

**step** `string` *required*

A step name from the [step table](#setup-steps).

**--device** `string`

Which phone, when the step belongs to a phone and more than one is plugged in. Use the phone ID shown by `setup status`.

**--json** `flag`

Print the full setup report as JSON after the step.

What happens depends on the step's kind (see [step kinds](#step-kinds)):

* **A step you do on the phone or the Mac**, such as `developer_mode`: `scrollyctl setup <step>` makes the Mac re-read everything now, then prints where that step stands. Run it after you have changed the setting, instead of waiting for the next automatic read.
* **`mac_never_sleeps`**: runs `sudo pmset -a sleep 0`. `sudo` asks for your Mac password. This only works in your own Terminal window. If the command is not running in a terminal, it stops with `needs_terminal` and tells you what to run.
* **`wda_installed`**: the Mac builds and installs WebDriverAgent by itself. `setup wda_installed` re-reads it, and makes a build that failed try again now rather than in 30 minutes.
* **`photos_add_access`**: asks the selected phone for add-only Photos access. Look at the phone and tap **Allow** when it asks. With more than one phone you must pass `--device`.
* **`setup add-phone --device <udid>`**: adds a phone that was removed in the console and is still plugged in. The setup report lists these under `waitingPhones`.
* **A step that is not a command step**: Safari's lock and the settings an Admin confirms in the console are checked elsewhere. `setup` refuses them and says who does them.

## skill install

Installs the [setup skill](https://docs.tryscrolly.com/agents/setup-skill.md) for your AI agent and prints the line to ask it.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl skill install [--dir <folder>] [--json]
```

**--dir** `path`

The agent's skills folder. Defaults to Claude Code's, `~/.claude/skills`.

**--json** `flag`

Print the result as JSON.

It writes `<folder>/scrolly-setup/SKILL.md`. Running it again is safe: an identical copy is left alone and a different one is replaced whole. It never writes through a symbolic link. See [the setup skill](https://docs.tryscrolly.com/agents/setup-skill.md#where-it-installs) for details.

```text theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
Installed the scrolly-setup skill at /Users/you/.claude/skills/scrolly-setup/SKILL.md.

Now ask your AI agent:

  Set up Scrolly on my Mac. Read the scrolly-setup skill, run `scrollyctl setup status`, then walk me through each step and run the shell parts for me.
```

The first word is `Updated` when it replaced an older copy and `Already installed:` when nothing changed. With `--json` the result has `schemaVersion` (`1`), `skill`, `path`, `outcome` (`installed`, `updated` or `unchanged`) and `prompt`.

## wda team

Stores your Apple Developer team ID on this Mac, once. The Mac app does this for you after your Xcode sign-in; use the command when it finds no team. With it, and Xcode signed in to your account, the Mac builds and installs WebDriverAgent by itself for every phone driven by WDA. It is kept only on this Mac.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl wda team <team ID>
scrollyctl wda team            # prints the stored team ID
scrollyctl wda team --clear    # forgets it
```

## wda setup

Builds, signs and installs WebDriverAgent by hand on a supported iPhone, the same build the Mac makes by itself. Use it to watch a build that failed. It only builds WebDriverAgent. It never chooses how a phone is driven.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
scrollyctl wda setup --device <phone ID> [--team <team ID>] [--register]
```

Run it in your own Terminal. It signs with the Apple Developer account you have signed in to in Xcode, and `scrollyctl` never asks for or reads your Apple ID, password or keys. It downloads a pinned copy of WebDriverAgent, checks its hash, builds it for the phone and installs it. This takes a few minutes. Let it finish.

**--team** `string`

Your Apple Developer team ID: ten capital letters and digits, such as `A1B2C3D4E5`. Find it on developer.apple.com under Account, Membership details. It is not a secret. Without it, the team stored with [`wda team`](#wda-team) is used; with it, it is stored for this Mac.

**--device** `string` *required*

The phone's ID, copied from `scrollyctl setup status`.

**--register** `flag`

Let Xcode register the phone to your team if it is not registered yet. Add it only when the build says the phone is not registered.

**--dir** `path`

Where the Mac's configuration lives. Defaults to this Mac's.

When it finishes it prints `WebDriverAgent is installed for <phone ID>. The Mac starts it by itself; run scrollyctl setup status to see what is left.`

`scrollyctl wda remove --device <phone ID>` removes the saved build from the Mac. The driver app already on the phone and your driver mode choice are kept.

## The setup report

`scrollyctl setup status --json` prints one JSON document. `schemaVersion` is `1`. It changes only when a field is removed or changes meaning. New fields can be added without a version change, so ignore fields you do not know.

```json theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
{
  "schemaVersion": 1,
  "provider": { "id": "mac-7kq2mx9d4fab", "name": "Studio Mac", "connected": true },
  "mac": {
    "supportedPhones": 1,
    "steps": [
      {
        "id": "mac_never_sleeps",
        "state": "pending",
        "reason": "This Mac sleeps after 10 minutes idle, which drops every phone on it",
        "nextAction": "Set the Mac never to sleep: sudo pmset -a sleep 0"
      }
    ]
  },
  "phones": [],
  "waitingPhones": [],
  "heldElsewherePhones": [],
  "remaining": [
    {
      "scope": "mac",
      "deviceId": null,
      "step": "mac_never_sleeps",
      "state": "pending",
      "kind": "command",
      "reason": "This Mac sleeps after 10 minutes idle, which drops every phone on it",
      "nextAction": "Set the Mac never to sleep: sudo pmset -a sleep 0",
      "command": "scrollyctl setup mac_never_sleeps"
    }
  ],
  "readyToSchedule": false
}
```

**readyToSchedule** `boolean`

`true` when at least one phone is plugged in and every phone the Mac reports on is ready to schedule. A phone the Mac has no status for does not count as ready. The Mac reports its setup reading. The console also checks whether a particular post can run.

**provider** `object`

`id` and `name` of this Mac, and `connected`: whether the Mac is registered with Scrolly. While it is `false`, the steps Scrolly answers read as waiting.

**mac** `object`

`supportedPhones` is the Mac's phone capacity. `steps` is this Mac's checklist.

**phones** `array`

One entry per reported phone, with `deviceId`, `name`, `model`, `osVersion`, `status` and `setup`. The name, model and iOS version can be `null`. `setup` is `null` while the Mac has no setup reading. Use the phone's ID with `--device` to select it.

**waitingPhones** `array`

Removed phones that are still plugged in and can be added back.

**heldElsewherePhones** `array`

Phones linked to another team. They are listed apart from the phones your Mac can use.

**remaining** `array`

Every step that is not done, in the order to do it: the Mac's first, then each phone's. Each entry has `scope` (`mac` or `phone`), `deviceId` (`null` for the Mac), `step`, `state` (`pending` or `unknown`), `kind`, `reason`, `nextAction` and `command`. `command` is the `scrollyctl` command that does the step or re-reads it, and is `null` when none applies.

Each step in `steps` has `id`, `state` (`done`, `pending` or `unknown`), `reason` and `nextAction`. The last two are `null` when the step is done.

### Step kinds

Each remaining step has a `kind` that says who finishes it.

| `kind` | Who | What to do |
| - | - | - |
| `command` | `scrollyctl` | Run `scrollyctl setup <step>` (or `wda setup`). |
| `customer` | You | Do it on the phone or the Mac, then run `scrollyctl setup <step>` to re-read it. Use the report's `nextAction` for steps without a command. |
| `console` | An organization Admin | Confirm it in the Scrolly console. `scrollyctl` cannot. |
| `automatic` | The Mac | Keep the phone plugged in, unlocked and trusting the Mac, then wait and re-read. |

### Setup steps

Find the step names you need in the report. The Xcode, signing, driver app and Photos access steps apply to WDA phones. The report can list them separately as optional steps for a phone that uses Native.

| Step | Kind | Title in the checklist |
| - | - | - |
| `ios_version` | customer | Phone's iOS supported (WDA from iOS 15, native from iOS 27) |
| `usb_trust` | customer | Phone connected and trusts this Mac |
| `developer_mode` | customer | Developer Mode on |
| `disk_image` | automatic | Developer disk image mounted |
| `xcode_installed` | customer | Xcode installed on this Mac |
| `signing_identity` | customer | Apple developer signing set up in Xcode |
| `wda_installed` | automatic | WebDriverAgent built and installed on the phone |
| `developer_app_trusted` | customer | Developer app trusted on the phone |
| `wda_running` | automatic | WebDriverAgent running |
| `photos_add_access` | command | Photos access allowed for WebDriverAgent |
| `dnd_on` | customer | Do Not Disturb on |
| `auto_lock_never` | console | Auto-Lock set to Never |
| `safari_unlocked` | customer | Safari not locked with Face ID |
| `icloud_photos_off` | console | iCloud Photos off |
| `handoff_off` | console | Handoff off |
| `safari_downloads_local` | console | Safari downloads kept on the phone |
| `app_store_auto_update_off` | console | App Store automatic updates off |
| `display_zoom_standard` | console | Display Zoom standard |
| `text_size_default` | console | Text size default |
| `tiktok_installed` | customer | TikTok installed |
| `file_sharing_app` | customer | Chrome installed (recommended: media over the cable) |
| `account_verified` | console | TikTok account bound and verified |
| `phone_verified` | console | Test this phone |
| `mac_never_sleeps` | command | Mac set never to sleep |
| `mac_capacity` | customer | Phone within this Mac's supported count |
| `proxy_client_installed` | customer | Stash installed (proxy); optional, only for a phone with a proxy |
| `proxy_profile_imported` | customer | Proxy profile imported into Stash; optional |
| `proxy_vpn_on` | customer | Stash VPN on; optional |
| `proxy_control_reachable` | automatic | Stash control reachable from this Mac; optional |

## Errors

When `scrollyctl setup` cannot produce a report, plain output goes to standard error as `scrollyctl: <message>` followed by `Next: <what to do>`. With `--json` it prints this document to standard output instead, so a caller can tell why:

```json theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
{
  "schemaVersion": 1,
  "error": {
    "code": "not_enrolled",
    "message": "this Mac is not linked to an organization yet",
    "nextAction": "Create a pairing code in the console (Add a Mac), then run: scrollyctl enroll <code>"
  }
}
```

| `code` | Meaning | What to do |
| - | - | - |
| `not_enrolled` | This Mac is not linked yet. | Create a pairing code in the console (**Add a Mac**) and run `scrollyctl enroll <code>`, or run `scrollyctl link`. |
| `provider_unreachable` | The Scrolly provider on this Mac is not running, or was set up before it could report setup status. | Choose **Restart services** in the Scrolly Mac app or run `scrollyctl restart`, then read the status again. If the provider predates setup status, install the current installer and enroll again with a new code. |
| `needs_terminal` | The step asks for your Mac password, or needs a different command. | Open Terminal and run the command in `nextAction` yourself. |
| `refused` | The request was refused: not a step name, not a command step, or a phone must be selected with `--device`. | Read the message. For an unknown step it lists the valid names. |
| `failed` | Something else went wrong, such as an unreadable configuration or a `sudo` that did not succeed. | Read the message. Do not retry in a loop. |

### Exit status

| Status | Meaning |
| - | - |
| `0` | A report or result was printed. |
| `1` | The command failed. |
| `2` | `setup <step>` was given a name that is not a step or a step that is not a command step, or the arguments were invalid. |

Other refusals, such as a missing `--device`, and `needs_terminal` for `mac_never_sleeps` exit with `1`. Use the JSON `error.code`, not the exit status, to tell failures apart. `enroll`, `link`, `skill install` and `wda setup` print `scrollyctl: <message>` to standard error and exit with `1` on failure.

## Next steps

> [card] [Setup skill](https://docs.tryscrolly.com/agents/setup-skill.md)
>
> Let your AI agent walk you through setup with scrollyctl.

> [card] [Phones](https://docs.tryscrolly.com/guides/phones.md)
>
> What a phone's card says, and why it isn't running.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.