# CLI reference

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

Source: https://runfoundry.app/docs/reference/cli/

## 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.

| Command | What it does |
| --- | --- |
| `foundry doctor` | What is blocking this Mac and each phone, and the command that fixes it |
| `foundry status` | One 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 enroll` | Registers 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 add` | Links a signed-in account to its phone |
| `foundry accounts list` / `remove` / `enable` / `disable` | Shows, 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 plan` | Builds one day of posts from your list of videos |
| `foundry warm-plan` | Extends the warm-up schedule from your accounts |
| `foundry install-agents` | Starts the scheduled post-runner, warm-runner and warm-plan |
| `foundry pause` / `resume` | Stops and restarts posting; warm-ups are separate |
| `foundry watch` | Live results as posts run |
| `foundry incidents` | Every failed or unknown post as a small bundle for your agent |
| `foundry update` | Moves to a newer version |
| `foundry version` | The 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.

| Line | What it checks | If it fails |
| --- | --- | --- |
| `xcode` | Xcode is installed and selected | Install Xcode from the App Store and open it once |
| `devicectl` | Xcode 15 or newer, which talks to the phones | Update Xcode |
| `python` | Python 3.9 or newer | `xcode-select --install` |
| `FOUNDRY_HOME` | The folder Foundry keeps everything in | Run the install line again |
| `fleet manifest`, `accounts.json` | Your phones and accounts files, and how many are on | Run the install line again; nothing is lost |
| `ocr binary` | The helper that reads the phone screen | Run the install line again |
| `provisioning profiles` | A signing profile for the runner on this Mac. `0` is normal before your first phone | Sign 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-plan | `foundry install-agents`, once a phone is enabled |
| Phone lines | Each phone this Mac knows, its state and the next command | Run the command after `->`. `state=unavailable` means it is not on the cable right now |

## foundry license

Terminal:

```bash
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](https://runfoundry.app/account).

## 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:

```text
usage: foundry enroll [-h] [--udid UDID] [--name NAME] [--model MODEL] [--port PORT]
```

| Option | Meaning |
| --- | --- |
| `--udid UDID` | Which phone, when this Mac knows more than one. `foundry doctor` prints each phone's id |
| `--name NAME` | The 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:

```bash
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](https://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:

```bash
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
```

| Option | Meaning |
| --- | --- |
| `--id` | Your name for the account, used by every other command |
| `--platform` | `instagram`, `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](https://runfoundry.app/support). Facebook is not an account here: it rides an Instagram account's Share to Facebook. Every platform's status is on [What Foundry posts](https://runfoundry.app/docs/operations/post-kinds/) |
| `--phone` | The phone it is signed in on, as named at `foundry enroll`; the phone must be enrolled first |
| `--handle` | The 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 |
| `--posts` | Posts a day in the daily plan; each needs its own clip, so `--posts 2` needs 2 different clips |
| `--warms` | Warm-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:

```bash
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:

```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](https://runfoundry.app/docs/operations/videos/).

## Running every day

Terminal:

```bash
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
```

> **No double posts.** A post whose share tap happened but couldn't be confirmed is marked `unknown` and is never retried. Check the account in the app.

## foundry update

Shows how to move to a newer version. The install line from [Install](https://runfoundry.app/docs/get-started/ai-agent/#install) does the same: run it again and your phones, accounts, plans and receipts are kept.
