CLI reference

@nomac/cli — a full Mac session from your terminal or agent. Requires Node 20+ and OpenSSH; sync/pull also need rsync. Use WSL on Windows for this workflow. Also see the API reference and the agent install page.

Cloud Mac sessions

Add credit at Your Mac, or from the CLI with nomac credits buy --packs N, which opens a payment link. Mac time is $0.80 an hour, billed by the minute; $10 buys 12.5 hours and credit never expires. nomac credits shows what is left. A Builder subscription is separate. Install the CLI for hosted sessions:

npm install -g @nomac/cli
nomac login
nomac start --json
nomac sync .
nomac ssh
nomac pull ./build
nomac stop --json

Run these in your project directory. Wait for ready before connecting. Queue/setup time is free; time between commands on a ready Mac counts. Disconnecting does not stop the session. Download files before stopping: stopping deletes the VM and its files.

Native SSH is the flexible path for long commands and transfers requiring symlinks. A local rename can leave the old remote source file: remove obsolete files explicitly. Managed output keeps an 8-MiB combined prefix and, if truncated, a final 64-KiB tail per stream. Tail offsets refer to original bytes. Older output may expire while its completion receipt remains; never rerun a command just to retrieve logs. All guest output disappears when the VM is deleted.

The current hosted CLI does not have nomac run or a session nomac logs alias. For MCP, see the agent setup and full agent guide.

Secrets, signing and shipping

Your App Store Connect key, connected once at Apple, stays on NoMac's server: it never reaches a Mac. Secrets are entered by you, never shown back, and every Mac you start receives them, with their values masked in command output.

Paths are on the Mac, relative to the synced folder. Steps only a person can take, such as creating the app in App Store Connect or accepting Apple's agreements, are printed with their link.

Builder commands

For existing Builder subscribers only: the Builder plans are closed to new subscriptions. These commands drive the separate build, TestFlight and App Store workflow and do not start full Mac sessions. For a Mac, use the session commands above.

Configuration

Builder by hand (existing subscribers)

Everything an agent does over MCP, you can do by hand. One-time setup: sign in at nomac.app, connect your Apple Developer account with an App Store Connect API key (the dashboard wizard walks you through it), then:

cd YourApp/               # the folder with the .xcodeproj
npx @nomac/cli login      # approve in the browser, once per machine
npx @nomac/cli push       # upload a snapshot + run review lint
npx @nomac/cli build --testflight

About 3 minutes later the build is on your phone in TestFlight. From there the loop is push → build → test on device → repeat. When a build fails, nomac logs shows the failing step and excerpt.

Metadata, screenshots, review checks and the App Store submission itself have no CLI subcommands yet — drive them with curl against the REST API (/review-lint, /metadata, /screenshots, /publish), or let an agent do it. The MCP tools get_review, update_review, prepare_review_reply, get_testflight and manage_testflight cover review and external beta actions. Reviewer correspondence still requires App Store Connect; reply drafts are never reported as sent.

get_store_capabilities, read_store and update_store cover paid pricing/availability, subscriptions, in-app purchases and offers, public customer-review replies, phased releases, product pages, analytics and app webhooks. Discovery returns the exact Apple schemas; reads return reusable app-owned scopes. Writes preview by default and require confirm:true.

upload_store_asset accepts a local file_path for reviewer documents, previews, purchase images and other Apple file resources. It reserves the file, streams Apple's requested byte ranges and commits the checksum. Preserve request_key and the original bytes to resume; poll until ready:true.

Builder in CI/CD (existing subscribers)

The CLI runs on plain Linux runners — no macOS runner, no certificates, no fastlane. Authenticate with NOMAC_API_KEY:

1. Create a key: dashboard → API keys (or nomac login locally and reuse it).
2. Store it as a repo secret named NOMAC_API_KEY.
3. Commit .nomac.json (created on your first nomac push) so CI builds the same project.

Ship every push to main to TestFlight:

# .github/workflows/testflight.yml
name: TestFlight
on:
  push:
    branches: [main]

jobs:
  testflight:
    runs-on: ubuntu-latest
    env:
      NOMAC_API_KEY: ${{ secrets.NOMAC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @nomac/cli push
      - run: npx @nomac/cli build --testflight

Cheap compile check on pull requests (smoke builds don't sign or upload):

# .github/workflows/smoke.yml
name: Smoke build
on: pull_request

jobs:
  smoke:
    runs-on: ubuntu-latest
    env:
      NOMAC_API_KEY: ${{ secrets.NOMAC_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @nomac/cli push
      - run: npx @nomac/cli build --smoke --wait

Worth knowing before you wire this to every commit:

• Every build attempt counts toward your monthly cap (Starter 50, Pro 300) — including failed ones. Gate the TestFlight job on main, use smoke builds for PRs.
• Build numbers (CFBundleVersion) increment automatically per project — no version bumping step needed. Bump the marketing version in your Xcode project when you cut a release.
• build --testflight exits non-zero on failure, so the job fails visibly; run npx @nomac/cli logs (or GET /builds/:id/failure) to see why.
• POSTs accept an Idempotency-Key header — the CLI already sends one, so a retried CI step won't double-start a build.

Questions: support@nomac.app · Agents can file issues directly with the report_issue tool.