Skip to main content
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.
Run scrollyctl --help or scrollyctl <command> --help to see the built-in help.

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>). 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.
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.
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.
string
required
The pairing code from the console.
string
What to call this Mac in the console. Defaults to the Mac’s computer name.
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.
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.
path
Where the Mac’s configuration and credentials live. Defaults to ~/Library/Application Support/Scrolly. You do not normally need it.
flag
Print the result as JSON for an AI agent. It never contains a secret.
flag
Do not restart the Scrolly background services afterwards.
On success enroll prints something like:
When the Mac was already linked it says Enrolled again. With --json it prints these fields:
string
The Mac’s ID.
string
The Mac’s name in the console.
string
The address the console uses to reach this Mac.
boolean
true when an existing link was replaced in place.
boolean
Whether remote access to this Mac is set up.
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.
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.
Links this Mac by approving it in your browser, with no code to type.
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.
string
What to call this Mac. Defaults to its computer name.
flag
Add this Mac as a new one even if it is already linked.
flag
Print the page address instead of opening your browser. You can open it on another computer and enter the code there.
flag
Show the code and the result in dialogs instead of Terminal text.
flag
Print one JSON object per line, for the Scrolly Mac app’s window.
string
As for enroll.
path
As for enroll.
flag
Do not restart the Scrolly background services afterwards.

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.
flag
Print the versioned setup report as JSON, for an AI agent.
flag
Have the Mac read its sleep setting and each phone’s apps again before reporting, instead of reporting what it last read.
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.
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.
<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 _.
string
required
A step name from the step table.
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.
flag
Print the full setup report as JSON after the step.
What happens depends on the step’s kind (see 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 for your AI agent and prints the line to ask it.
path
The agent’s skills folder. Defaults to Claude Code’s, ~/.claude/skills.
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 for details.
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.

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.
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.
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 is used; with it, it is stored for this Mac.
string
required
The phone’s ID, copied from scrollyctl setup status.
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.
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.
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.
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.
object
supportedPhones is the Mac’s phone capacity. steps is this Mac’s checklist.
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.
array
Removed phones that are still plugged in and can be added back.
array
Phones linked to another team. They are listed apart from the phones your Mac can use.
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.

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.

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:

Exit status

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

Setup skill

Let your AI agent walk you through setup with scrollyctl.

Phones

What a phone’s card says, and why it isn’t running.