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.
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 setupcannot 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. scrollyctlnever asks for a password and never passes one on. The one step that needs your Mac password runssudoin your own Terminal window, andsudoasks you there.
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.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.
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.
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.Where the Mac’s configuration and credentials live. Defaults to
~/Library/Application Support/Scrolly. You do not normally need it.enroll prints something like:
Enrolled again. With --json it prints these fields:
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.
link
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.
Print the page address instead of opening your browser. You can open it on another computer and enter the code there.
open
--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.Print the versioned setup report as JSON, for an AI agent.
Have the Mac read its sleep setting and each phone’s apps again before reporting, instead of reporting what it last read.
--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.
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 _.
A step name from the step table.
Which phone, when the step belongs to a phone and more than one is plugged in. Use the phone ID shown by
setup status.- 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: runssudo pmset -a sleep 0.sudoasks for your Mac password. This only works in your own Terminal window. If the command is not running in a terminal, it stops withneeds_terminaland tells you what to run.wda_installed: the Mac builds and installs WebDriverAgent by itself.setup wda_installedre-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 underwaitingPhones.- A step that is not a command step: Safari’s lock and the settings an Admin confirms in the console are checked elsewhere.
setuprefuses them and says who does them.
skill install
Installs the setup skill for your AI agent and prints the line to ask it.<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.
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.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.
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.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.
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.
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.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.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.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.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 akind 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
Whenscrollyctl 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.