# CLI reference @nomac/cli runs a cloud Mac from your terminal or your agent. Run it in your project's folder: each folder remembers its Mac. ## Terminal ``` npm install -g @nomac/cli nomac login nomac start nomac sync . nomac exec --wait 600 -- xcodebuild -scheme App build nomac pull ./build nomac stop ``` It needs Node 20 or later and OpenSSH, which macOS and Windows 10 and 11 include; on Windows it runs in PowerShell or cmd. It updates itself in the background, and `nomac --help` lists everything below. ## Account - **nomac login** Connects this device: prints a link and a short code to approve in the browser, then keeps the key in `~/.nomac/credentials.json`. Nothing secret is typed in the terminal. - **nomac login --with-token < key.txt** Uses a key made at [nomac.app/dash/keys](/content/dash/keys/index.html) instead, read from stdin so it stays out of your shell history. - **nomac whoami** The account, the credit left and how this device is signed in. - **nomac credits** The credit left. `nomac credits buy --packs 3` opens a payment link. - **nomac feedback "..."** Tells NoMac what got in your way, failed, was missing or was slow. A person reads each one. - **nomac update** Installs the newest CLI now. `NOMAC_NO_AUTO_UPDATE=1` turns off updating in the background. ## Start and stop - **nomac start** Starts a Mac, or reconnects to this folder's. It runs 2 hours by default (`--max-duration`, up to 8 hours), stops after 10 idle minutes (`--idle-timeout`) and spends $5 at most (`--max-cost`). - **nomac start --parallel** A second Mac beside the account's running one, from another folder, once the account has bought credit and while NoMac has a Mac to spare. It gets a drive of its own while the first has the default, and says which. - **nomac start --queue 1800** Waits in line, free, for the account's running Mac to stop (or the drive asked for, or at a busy hour a free Mac), then starts: 300 to 3,600 seconds. Without it, such a start is refused and names the running Mac. - **nomac attach [SESSION_ID]** Uses from this folder the Mac your agent started elsewhere, over MCP or in the dashboard. - **nomac status** State, cost so far and when the Mac stops. `--json` adds usage and deadlines. - **nomac extend 60** Keeps the Mac running longer: its time limit goes up by the minutes given (60 by default, 8 hours in all), and its spend cap with it. - **nomac stop** Stops the Mac and deletes it with every file outside ~/drive. Billing ends. Download anything else first. While another API key sent the Mac a command or opened SSH to it in the last 5 minutes, it asks for --confirm. ## Run commands - **nomac exec -- COMMAND** Runs a command, prints its output as it arrives and exits with its code. It waits up to `--wait` seconds (30 by default); use `--wait 600` for builds and tests. `--timeout`, how long the command may run, goes up to 3600 seconds. - **nomac run -- COMMAND** One command on a fresh Mac of its own (without a drive, unless `--drive NAME` names one), then the Mac is stopped, for CI systems and scripts: start, upload this folder, run it (its output on stdout as it arrives, its exit code), copy back what `--pull` names, stop. It never uses or stops a Mac you already run. `nomac run --help` lists its options. - **nomac job JOB_ID --wait 600** Waits for a command that outlasted --wait, then prints its output and exits with its code. It never runs the command again. - **nomac output JOB_ID --stream stdout** Reads a command's full output from `--cursor`, for stdout or stderr. - **nomac cancel JOB_ID** Stops a running command and everything it started. - **nomac ssh** Opens a shell on the Mac. `nomac ssh -- COMMAND` runs one, also past an hour, and `--forward 8080:3000` forwards a port. - **nomac ssh-config** Names this folder's Mac `nomac` in your SSH config, for VS Code or Cursor Remote-SSH, Claude Code's SSH sessions and `ssh nomac`. Each start or attach points it at the new Mac. Exit code 75 means the command is still running on the Mac: follow it with `nomac job`, never run it again. In scripts, add `--request-key KEY` and reuse it after a lost answer. ## Files - **nomac sync .** Uploads what changed to `~/drive/src/`, kept between sessions. It skips `node_modules`, Pods, DerivedData, build folders, `.git` and what `.gitignore` lists, and keeps secrets on your computer: `.env` files, `.p8`, `.p12`, keystores and private keys (`nomac secrets` gives them to every Mac encrypted). A `!` line in `.nomacignore` sends any of them. `--watch` keeps syncing until Ctrl-C, and `--delete` removes on the Mac what you deleted here. - **nomac pull ./build --from build** Copies a folder or file from the Mac. `--from` is relative to the project folder there. `--overwrite` replaces local files that differ. - **nomac drive** The account's drives (each Mac has one at `~/drive`): space used and which Mac has each. `nomac drive reset NAME` empties one, `nomac drive rename OLD NEW` renames one. - **nomac start --drive NAME** This Mac with that drive, made empty the first time; the folder asks for it again at its next start. `--drive-from default` starts it as a copy, `--reuse` gives you the running Mac that has it. ## Screen and input - **nomac desktop** The Mac's desktop in your browser. `--app`, on a Mac, opens Apple's Screen Sharing with a shared clipboard. - **nomac screenshot** Saves the screen, or with `--simulator` the Simulator, as a JPEG. - **nomac input type TEXT** A real keyboard and mouse: `type`, `key cmd+q`, `click X Y`, `move`, `scroll`, `password`. It reaches the lock screen and password dialogs, and saves a screenshot after. - **nomac unlock** Unlocks the lock screen with the session's password. - **nomac record** Starts a video of the screen, or with `--simulator` the Simulator. `nomac record stop` saves the MP4 with a share link. ## Access - **nomac password** The Mac's login password for this session, for the keychain or a macOS prompt. On the Mac it is `$NOMAC_MAC_PASSWORD`. - **nomac permit APP camera microphone** Grants an app privacy permissions by bundle ID, so it never asks: camera, microphone, contacts, calendars, reminders, photos, desktop, documents, downloads, or `all`. At start: `--permit APP=camera,microphone`. - **nomac start --prompts ask** Keeps macOS's usual prompts for this Mac. By default the Mac is fully open to your agent. - **nomac defaults** What every new Mac starts with. `--prompts ask` and `--permit` change them, `--reset` goes back to fully open. A start's own options win for that Mac. ## Secrets - **nomac secrets set NAME** Saves a variable, its value from stdin (hidden when typed), never from an argument. `--file PATH` saves a file of up to 1 MiB, `--from-env-file .env` every line, and `--on-request` installs it only when named. - **nomac secrets** Lists them by name, where each goes and its size. `nomac secrets rm NAME` deletes one. - **nomac secrets install [NAME...]** Puts on-request secrets on this folder's running Mac by name, or installs again after a failed install. Changes to the others reach running Macs within a minute on their own. - **nomac secrets request NAME --description TEXT** Makes a link where whoever holds the secret enters it once, in the browser, with no NoMac account. ## Sign and ship - **nomac apple** Whether Apple is connected: the team key, the certificates every Mac receives and the profiles. - **nomac sign [path]** Sets up App Store signing for the project on the Mac and prints a build settings file, export options, the reserved build number and the build commands for xcodebuild, Flutter and fastlane. The project is not changed. - **nomac testflight App.ipa** Sends a signed .ipa on the Mac to TestFlight and follows it until it is there. `--notes` sets What to Test, and `--encryption no|yes` answers Apple's export question once per app. - **nomac publish App.ipa** Sends the build, sets What's New with `--whats-new` and stages the version with Apple's blockers. Nothing goes to App Review until you run it again with `--confirm`. - **nomac notarize App.app** Notarizes a Developer ID-signed .app, .dmg, .pkg or .zip and staples the ticket. Sign first with `codesign --options runtime --timestamp`. Paths are on the Mac, relative to the synced folder. Metadata, screenshots and review checks have no commands: your agent does them over MCP, or `curl` the [Mac API](/content/docs/api/index.html). ## Agents - **nomac mcp** Runs the MCP server over stdin and stdout, for Claude Code, Codex, Cursor and others. See [Connect your agent](/content/docs/connect/index.html). ## Configuration - **NOMAC_API_KEY** A key that overrides the stored one: the way to sign in from CI and scripts. - **NOMAC_API_URL** The API's address, `https://nomac.app` by default. - **~/.nomac/credentials.json** The key `nomac login` keeps, readable only by you.