Reference

Every foundry command, what it does and its options, as the current release prints them.

Overview

The foundry command is installed at ~/.local/bin/foundry and keeps everything it knows in ~/Library/Application Support/Foundry. Each command below is copied from the release's own help; foundry <command> --help prints the same on your Mac.

CommandWhat it does
foundry doctorWhat is blocking this Mac and each phone, and the command that fixes it
foundry statusOne screen: phones, today's plan, warm-ups, last events. post-runner: never ticked is normal until its first planned minute; a later day's plan is the file drip-plan-<date>.json in the fleet folder
foundry lanes [--all]Each enrolled phone: its port, ready or down (whether its runner answers), and DISABLED if it is off. foundry doctor also checks the cable and the signing
foundry runner [--date D]Shows what the post-runner would post now (mode: shadow means it only looked); the scheduled agent runs it for real
foundry license activate <key>Turns your key on for this Mac and takes one Mac seat
foundry enrollRegisters a plugged-in, trusted iPhone as a phone (off until proven)
foundry lane up <phone>Signs and installs the runner on the phone and opens its session
foundry accounts addLinks a signed-in account to its phone
foundry accounts list / remove / enable / disableShows, deletes, or turns an account on and off (--id <account>). To change one, remove it and add it again
foundry test-post [--account ID] [--video FILE] [--publish]End-to-end 60-second verification on a ready phone (auto-generates a 3s vertical test clip if no --video is given; dry-run up to Share by default, or --publish live)
foundry planBuilds one day of posts from your list of videos
foundry warm-planExtends the warm-up schedule from your accounts
foundry install-agentsStarts the scheduled post-runner, warm-runner and warm-plan
foundry pause / resumeStops and restarts posting; warm-ups are separate
foundry watchLive results as posts run
foundry incidentsEvery failed or unknown post as a small bundle for your agent
foundry updateMoves to a newer version
foundry versionThe installed version and where its files are (foundry --version prints just the number)

foundry doctor

Run it first, and again after any change. When setup is done (a phone up and enabled, an account, the agents installed) it ends ready. Each line starts ok, FAIL or -- (not set up yet), and the last line says ready or NOT ready. An enrolled phone that is not ready ends in <- and why (disabled, or coredevice not connected and wda down: plug it in, then foundry lane up <phone>; coredevice not seen, wda ready means the runner answers but the phone is off the cable: plug it back in, posts need the cable). An (unenrolled) line ends in -> with the command to enroll it, only if that phone is yours.

LineWhat it checksIf it fails
xcodeXcode is installed and selectedInstall Xcode from the App Store and open it once
devicectlXcode 15 or newer, which talks to the phonesUpdate Xcode
pythonPython 3.9 or newerxcode-select --install
FOUNDRY_HOMEThe folder Foundry keeps everything inRun the install line again
fleet manifest, accounts.jsonYour phones and accounts files, and how many are onRun the install line again; nothing is lost
ocr binaryThe helper that reads the phone screenRun the install line again
provisioning profilesA signing profile for the runner on this Mac. 0 is normal before your first phoneSign in to Xcode under Xcode › Settings › Accounts with your Apple Developer team, then foundry lane up <phone> --team <team id> makes it
agent com.foundry.*The scheduled post-runner, warm-runner and warm-planfoundry install-agents, once a phone is enabled
Phone linesEach phone this Mac knows, its state and the next commandRun the command after ->. state=unavailable means it is not on the cable right now

foundry license

Terminal
foundry license activate <key>   # turn the key on for this Mac, takes one Mac seat
foundry license status           # plan, phones enrolled, trial and expiry
foundry license release          # give this Mac's seat back

activate and status answer with one line, for example Solo: 0 of 1 iPhone enrolled, trialing, valid until 2026-11-09 (you@example.com). Your plan sets how many phones foundry enroll accepts and how many Macs can hold a seat. You can also free a seat from Billing › Mac seats on your dashboard.

foundry enroll

Registers a phone that is plugged in, unlocked and trusted. A new phone starts disabled, so nothing drives it until foundry lane enable.

Usage
usage: foundry enroll [-h] [--udid UDID] [--name NAME] [--model MODEL] [--port PORT]
OptionMeaning
--udid UDIDWhich phone, when this Mac knows more than one. foundry doctor prints each phone's id
--name NAMEThe name you use for the phone in every other command, for example 12-mini

foundry lane

A lane is one phone and its runner. Bring it up once, then turn it on.

Terminal
foundry lane up 12-mini --team ABCDE12345   # sign + install the runner under your Apple team, open the lane
foundry lane enable 12-mini                 # only after up reports ready
foundry lane disable 12-mini                # stop driving this phone

--team is your Apple Developer team id: the 10 character code (like A1B2C3D4E5) at developer.apple.com/account under Membership details, or in Xcode under Settings › Accounts with your team selected. It is asked for the first time a lane comes up on a Mac. Run lane up from Terminal on the Mac itself, not over SSH: signing needs the login keychain.

foundry accounts

Accounts are signed in on the phone by you, in the official app. This tells Foundry which phone each one lives on.

Terminal
foundry accounts add --id instagram-myhandle --platform instagram --phone 12-mini --handle myhandle --posts 2 --warms 2,3
foundry accounts list
foundry accounts disable --id instagram-myhandle
foundry accounts remove --id instagram-myhandle   # then add it again to change it
OptionMeaning
--idYour name for the account, used by every other command
--platforminstagram, tiktok or youtube in this release. X, Reddit, Snapchat and LinkedIn (x, reddit, snapchat, linkedin) post through the same runner in Beta; to add one on your Mac, ask in the support form. Facebook is not an account here: it rides an Instagram account's Share to Facebook. Every platform's status is on What Foundry posts
--phoneThe phone it is signed in on, as named at foundry enroll; the phone must be enrolled first
--handleThe exact handle. Instagram accounts that share a phone need it: Foundry switches by it and refuses to post if it can't confirm it on the profile
--postsPosts a day in the daily plan; each needs its own clip, so --posts 2 needs 2 different clips
--warmsWarm-up sessions a day; a list like 2,3 picks one at random each day

foundry plan

Builds one day of posts from your clips. Without --write it only shows the plan.

Terminal
foundry plan --date 2026-11-02 --videos videos.json --write

--start and --end (HH:MM, this Mac's local time) set the posting window; without them it runs from 08:05 to 01:45 (the small hours after the date). Every enabled account gets its posts at random times, never the same clip key twice on one platform (two keys on one file count as two clips), at least 18 minutes apart on one phone and clear of warm-ups. videos.json lists the clips:

videos.json

videos.json
[
  {
    "key": "M1",
    "path": "content/2026-11-02/M1.mov",
    "topic": "what the clip is about",
    "caption": "the caption that posts with it"
  }
]

More on preparing clips is on Your videos.

Running every day

Terminal
foundry warm-plan --days 7 # a week of warm-ups (30 without --days); the daily warm-plan agent keeps it going
foundry install-agents     # launchd: post-runner (every minute), warm-runner (every 5 minutes), warm-plan (daily)
foundry status             # morning: phones, today's plan, warm-ups
foundry watch              # during the day: live results
foundry incidents          # evening: every unknown or failed post
foundry incidents --resolve 2026-11-02-12   # after the cause is fixed
foundry pause              # stop posting (warm-ups keep running)
foundry resume

foundry update

Shows how to move to a newer version. The install line from Install does the same: run it again and your phones, accounts, plans and receipts are kept.

Copied