Documentation

Installation

Public CLI and MCP downloads are not available yet. You can open the workspace and explore the HTTP API reference. Join the waitlist to register your interest; joining does not send email or grant source access.

If you already have a source checkout

Use Python 3.11 or newer. Run these commands from the root of your existing gerberize checkout to install the CLI and MCP server in an isolated environment:

pipx install .

# Or install in your active virtual environment:
python -m pip install .

The package has not been published to a public package index. The commands above install from files already on your machine; they do not download a public release.

Install KiCad 9 or 10 for native design checks and exports, and ngspice for simulation. Make kicad-cli and ngspice available on your PATH. Missing executables produce actionable JSON errors.

gerberize --version
gerberize --help
gerberize fabs

CLI help is also JSON. The Docker image defined by this repository includes the service and native toolchain; see the repository deployment guide for build and worker commands.

Quickstart

Use the HTTP API

Sign in to the workspace, open Agent API keys, and create a named key. Save the key when it is shown, then provide it as GERBERIZE_API_KEY in your environment or secret manager. Keep the value private and out of source control.

This read-only request confirms your account and agent scope; it does not upload a file, create a job, or place an order:

curl --fail-with-body \
  -H "Authorization: Bearer ${GERBERIZE_API_KEY}" \
  https://gerberize.com/v1/me

Read data.user and data.scope in the JSON response. Agent keys cannot manage owner account controls or approve spending. The API reference documents endpoints and schemas; use bearer-authenticated requests from your client or curl for authenticated calls. Its interactive browser console does not automatically supply the CSRF token required for cookie-authenticated writes.

With an existing CLI checkout

After installing from your checkout, start with the board on your machine. Full validation runs native design-rule checks plus package and fabrication preflight.

gerberize validate controller.kicad_pcb \
  --fab oshpark-2layer \
  --schematic controller.kicad_sch \
  --bom bom.csv

gerberize export-gerbers controller.kicad_pcb --output output/gerbers
gerberize export-drill controller.kicad_pcb --output output/drill

Each command writes one JSON envelope and exits 0 for success or 1 for failure. Inspect errors and warnings; a successful preflight is not a manufacturing approval.

{
  "ok": false,
  "errors": [{
    "code": "FOOTPRINT_PITCH_MISMATCH",
    "message": "U5 pad pitch 0.5mm does not match expected 0.65mm (MSOP-8)",
    "ref": "U5",
    "fix_hint": "Use the MSOP-8 0.65mm footprint.",
    "position": {"x": 42.5, "y": 28.0}
  }],
  "warnings": [],
  "data": {}
}

This is an illustrative response. Actual findings include the references and coordinates available from your design.

Authentication

Local file checks need no account. Quotes, orders, uploads, and cloud jobs use the backend.

Sign in to the workspace

Open the workspace and choose Continue with Google to sign in or create an owner account. The button is enabled only when Google sign-in is configured on that deployment. Browser sessions use Secure, HttpOnly cookies; session secrets are not stored in browser local storage.

Already have an account created by an administrator? Open Advanced API key access, connect with its owner key, then choose Account → Link Google account. Accounts with the same email are never merged automatically. An advanced key stays only in the current page’s memory and is cleared on reload or sign-out.

From Account, update your display name and time zone, download your data, or deactivate your account. Sessions lets you revoke individual browser sign-ins or sign out all sessions. Agent keys are managed separately. Deactivation requires an ended subscription, no pending checkout, and no outstanding jobs or orders; retained billing and order history is not erased.

Connect the CLI

Point the CLI at your API origin:

export GERBERIZE_API_URL=https://gerberize.com
gerberize login

The response contains a device code, a user code, and a verification URL. Open that URL, sign in to your owner account, and approve only the code shown in a terminal you control. Then complete sign-in:

gerberize login --device-code YOUR_DEVICE_CODE --wait

The CLI stores the resulting agent token in a local configuration file with owner-only permissions. For automation, supply GERBERIZE_API_KEY through your environment or secret manager. Do not commit keys to configuration files.

Owner and agent access

An owner browser session or owner key can configure spend limits, manage billing and agent keys, and approve orders or CLI sessions. Keys created in the workspace and device-login tokens have agent access. Agents cannot change account settings, raise their own limits, or approve their own requests.

For a local deployment, an administrator can still provision an account with python -m gerberize.server.manage create-user --email you@example.com. Google browser sessions require HTTPS and configured OAuth credentials. The API reference documents authentication, account, and session routes.

Connect an agent

Install gerberize in an environment visible to your agent. The gerberize-mcp executable runs a local stdio server; it uses the same command registry, checks, and API authentication as the CLI.

Claude Code

claude mcp add --transport stdio gerberize -- gerberize-mcp

See Claude Code’s MCP documentation for project and user scopes.

Cursor

Add this server to .cursor/mcp.json in your project, or your user MCP configuration:

{
  "mcpServers": {
    "gerberize": {
      "command": "gerberize-mcp",
      "args": []
    }
  }
}

See Cursor’s MCP configuration reference.

Codex

codex mcp add gerberize -- gerberize-mcp

See the Codex MCP documentation for configuration and environment variables.

Tool naming

Every command is a tool named gerberize_<command>, with hyphens changed to underscores: gerberize_bom_check, gerberize_export_gerbers, and gerberize_order, for example. Input schemas match the command reference below. Tool results contain the same envelope.

The JSON contract

Every command returns exactly one object with these four required fields. Diagnostics include all five issue fields, with null where context is unavailable.

{
  "type": "object",
  "required": ["ok", "errors", "warnings", "data"],
  "properties": {
    "ok": {"type": "boolean"},
    "errors": {"type": "array", "items": {"$ref": "#/$defs/issue"}},
    "warnings": {"type": "array", "items": {"$ref": "#/$defs/issue"}},
    "data": {"type": "object"}
  },
  "$defs": {
    "issue": {
      "type": "object",
      "required": ["code", "message", "ref", "fix_hint", "position"],
      "properties": {
        "code": {"type": "string"},
        "message": {"type": "string"},
        "ref": {"type": ["string", "null"]},
        "fix_hint": {"type": ["string", "null"]},
        "position": {"type": ["object", "null"]}
      }
    }
  }
}

Download all command input and response schemas. The reference is generated from the Python command registry; regenerate it after adding commands.

Every command

Paths are positional. Other parameters use --kebab-case flags in the CLI and snake_case keys in MCP. Boolean flags take no value; provider lists use comma-separated names.

Fab capability profiles

Profiles are versioned JSON files, with manufacturer references linked where available. They compare trace width, clearance, drills, annular rings, layer count, board size, slots, and edge keepout where the board data and profile support the check.

gerberize fabs
gerberize fabcheck controller.kicad_pcb --fab partner-fab-2layer

Profile checks supplement native KiCad DRC. They are not a substitute for a fabricator’s DFM review. Unknown geometry or unsupported package recognition must remain visible as limitations.

Footprints and BOMs

Recognized package families include SOIC, TSSOP, MSOP, SOT-23/223, QFN with 0.5 mm pitch, and common 0402/0603/0805 passives. Pad count and pitch checks use the package library. Always match the exact manufacturer datasheet and pin assignment before release.

gerberize footprints controller.kicad_pcb
gerberize bom-check bom.csv
gerberize bom-check bom.csv --include-dnp

BOM checks cover missing MPNs, duplicate references, quantities, footprints, and DNP rows. Nexar, DigiKey, and Mouser provider interfaces require credentials and a configured API mapping; offline checks do not verify stock or lifecycle.

Simulation with limits

Use a self-contained .cir netlist or a KiCad schematic that can export a SPICE netlist. Supported analyses are operating point (op), transient (tran), and AC (ac).

gerberize simulate power.cir --analysis op --limits limits.json
gerberize simulate filter.cir --analysis tran --step 1u --stop 5m
gerberize simulate filter.cir --analysis ac --start 1 --stop 1meg --points 20

Example limits.json:

{
  "v(out)": {"min": 3.2, "max": 3.4}
}

Limits are applied to returned vectors. A missing requested signal or out-of-range value fails the command. Netlists with external includes, control commands, or other unsafe file/process operations are rejected. Supply supported self-contained models.

Cloud jobs

Run heavier validation and simulation on the deployed native worker. The CLI uploads the input, creates a persistent job, and can poll for completion.

gerberize validate controller.kicad_pcb --cloud --wait
gerberize simulate power.cir --analysis op --cloud --wait
gerberize jobs
gerberize job JOB_ID --wait

Preserve your project rules

For a board with project-specific design settings, upload a ZIP with exactly one board and its matching project file:

zip controller-project.zip controller.kicad_pcb controller.kicad_pro
gerberize validate controller-project.zip \
  --fab pcbway-standard --cloud --wait

Include a matching .kicad_dru file when your project uses custom rules. Keep the board, .kicad_pro, and rule files together with their original matching names. The worker preserves those files so native KiCad DRC uses the project settings. Archives accept only bounded KiCad board, project, rule, and schematic sources; unsupported files, unsafe paths, and links are rejected.

Jobs and uploaded bytes persist in PostgreSQL. Simulation inputs must be self-contained. Additional local schematic or BOM paths cannot be passed to a cloud job; including a schematic in a project ZIP does not automatically run ERC or BOM checks. Run those checks locally.

A queued job is not a successful validation. Inspect the completed job’s result envelope before proceeding.

Plans & billing

Free and Pro provide monthly cloud job allowances. Local CLI and MCP commands are not metered. The initial defaults are 10 cloud jobs per month on Free and 100 on Pro; deployments can configure both limits. Billing & usage shows the current plan, actual allowance, usage, and reset time from GET /v1/subscription.

Usage counts jobs created during the UTC calendar month, including jobs that later fail. Reusing an existing job does not create another usage entry. When the allowance is exhausted, new cloud jobs return CLOUD_JOB_QUOTA_EXCEEDED; local commands remain available.

Upgrade and manage a subscription

The workspace reads the recurring Pro price from the configured Stripe price. No public price is set in these docs. Upgrade to Pro opens hosted Stripe Checkout; Manage billing opens the Stripe customer portal. Available invoices link to Stripe. Pro is granted only after the server verifies an active subscription for the configured price; returning from Checkout alone does not change the plan.

For deployment administrators, configure STRIPE_SECRET_KEY, STRIPE_PRO_PRICE_ID, and STRIPE_SUBSCRIPTION_WEBHOOK_SECRET. Monthly limits use GERBERIZE_FREE_CLOUD_JOBS_PER_MONTH and GERBERIZE_PRO_CLOUD_JOBS_PER_MONTH. Credentials stay on the server. See the API reference for subscription, Checkout, portal, and invoice endpoints.

Subscription billing is separate from fabrication payments and spending caps. A Pro subscription never authorizes an order or raises a cap. Live fabrication remains disabled, and gerberize does not send invoice emails.

Spend guardrails

Ordering is blocked until you configure both a per-order cap and a monthly budget. The server reads the amount from a stored quote; client-supplied prices are not accepted.

1. The quote must belong to your account, remain valid, and support ordering.
2. The total must fit the per-order cap and available monthly budget.
3. If the total exceeds your approval threshold, the API returns APPROVAL_REQUIRED and a dashboard link.
4. An owner approves the quote and receives an expiring, single-use token. The token is bound to that quote and account.
5. The order request reserves budget before payment. Retries reuse the same idempotency key.

Approval cannot bypass either cap. Missing configuration, expired approvals, unavailable credentials, or unsupported adapters fail before payment or fabrication submission.

Try a sandbox order

The local sandbox fabricator never contacts a real manufacturer. An administrator must explicitly enable it with GERBERIZE_ENABLE_SANDBOX=1. For fully offline tests, use GERBERIZE_PAYMENT_MODE=mock_test.

Connect the owner dashboard, set spend limits, then use an agent key or device login from your terminal:

gerberize quote --providers sandbox \
  --quantity 5 --width-mm 50 --height-mm 50 --sort cost

gerberize order \
  --quote-id QUOTE_ID \
  --idempotency-key prototype-run-1

gerberize orders
gerberize track ORDER_ID --refresh

If approval is required, open the returned link in the owner dashboard. Copy the one-time token and repeat the order request with the same idempotency key:

gerberize order \
  --quote-id QUOTE_ID \
  --idempotency-key prototype-run-1 \
  --approval-token ONE_TIME_TOKEN

Fabrication test payments are configured separately through the owner billing API described in the API reference. The workspace billing screen manages subscriptions and does not accept raw customer or payment-method IDs. Fabrication payments accept test credentials only. No invoice email is sent.

Integration status

This preview intentionally distinguishes implemented local behavior from unqualified external integrations.

For exact verified deployment and test results, consult the README in the source repository.