Maglev CLI

The CLI calls Maglev’s HTTP API. It does not start another agent or require a different model.

CLI 0.6.14 includes browser approval and resumable login to project setup, local folder review, owner-authorized engineering transfers and reviewed live delivery actions.

Install

Requires Node.js 22.13 or later and npm:

npm install -g https://trymaglev.com/downloads/maglev-cli-0.6.14.tgz
maglev --version

Expected version: 0.6.14. This is the official @try-maglev/cli package distributed through Maglev’s immutable archive and SHA-256 checksum. The npm registry still serves 0.5.1; the new hosted release does not imply registry publication. Setup pins the matching hosted MCP 0.2.14 archive.

Upgrading from older archives

Versions through 0.5.0 used the package name @maglev/cli. If npm ls -g @maglev/cli --depth=0 lists that package, remove its global executable before installing the new name:

npm uninstall -g @maglev/cli
npm install -g https://trymaglev.com/downloads/maglev-cli-0.6.14.tgz
maglev --version

Project skills, environment credentials and saved example state are preserved. If npm reports EEXIST, inspect which package owns maglev; do not force-overwrite an unrelated executable. For a project-local dependency, run npm uninstall @maglev/cli and npm install https://trymaglev.com/downloads/maglev-cli-0.6.14.tgz in that project instead.

Connect your project

These setup commands are included in the hosted CLI 0.6.14 release. Older registry installations need the versioned upgrade above.

From your hardware project folder:

maglev setup

Setup connects your existing Maglev account, then lets you choose Claude Code, Codex, another MCP agent or terminal only with ↑ / ↓ and Enter. The current folder is used automatically. Account onboarding remains in the web app.

Project skills

maglev setup installs the project skill. To install only the skill, without signing in or configuring MCP:

maglev agent install --target claude --directory . --dry-run
maglev agent install --target claude --directory .

--target codex is also supported. The first command previews the destination; the second writes one SKILL.md from the installed CLI package. It uses no network or API key, leaves existing project guidance intact, and refuses to overwrite a different skill. Use maglev agent print to read the bundled instructions first.

Agent	Skill location inside your chosen project	Invoke it
Claude Code	.claude/skills/maglev-manufacturing/SKILL.md	/maglev-manufacturing
Codex	.agents/skills/maglev-manufacturing/SKILL.md	$maglev-manufacturing

These are the documented project skill locations for Claude Code and Codex. If a newly installed skill is missing from the agent’s picker, reopen its session. An installed skill follows the CLI version you installed; updating the website does not rewrite your local copy.

Any agent with HTTP or shell tools can instead read the public SKILL.md. The skill is an instruction document; your agent keeps its existing tools and permissions, and can use the credential for API requests without printing it or including it in its prompt.

Existing installations

CLI0.6.14 adds a managed project upgrade for recognized original Claude Code/Codex files. Preview with maglev agent upgrade --target claude --directory . --dry-run --json, then omit --dry-run to apply. The command keeps private backups and can resume an interruption. Use --target codex for Codex; custom configurations still need the manual review below.

A website update does not rewrite your project settings or installed skill. Setup preserves a different existing Maglev entry and stops with a configuration conflict before signing in. This includes older version pins; rerunning setup is not an automatic upgrade.

For an existing project, back up and review its Maglev MCP entry and skill first. Compare the current MCP configuration and maglev agent print. Retain other servers, environment settings and custom instructions; update only the reviewed Maglev version/skill, then reopen the host and verify get_identity. Hermes users review the installed Maglev server in its MCP settings. OpenClaw users review their workspace skill’s CLI prefix. Do not delete the whole configuration or overwrite custom guidance to suppress a conflict.

To try the new connector without changing an existing project configuration, connect from a new empty project directory. This uses the same saved account where available; it does not grant access to the older project’s files.

Commands

Command	Result
maglev setup	Connect your account, choose an agent and configure this project
maglev login	Approve a live connection in your browser and save the key privately
maglev login --sandbox	Connect a sandbox key for synthetic examples
maglev login --key	Use the hidden manual API-key entry fallback
maglev login --cancel	Cancel a pending browser connection and preserve your earlier login
maglev logout	Remove the saved credential for the current API
maglev setup --target codex --directory . --demo --json	The same setup without prompts; Claude Code and terminal-only setup are supported
maglev demo	Discover, inspect, save and retrieve a synthetic enclosure request; repeat to recover the same work
maglev agent print	Read the bundled agent instructions, without a key
maglev agent install --target claude --directory . --dry-run	Preview a project skill destination without writing
maglev agent install --target codex --directory .	Install the project skill; Claude Code is also supported
maglev doctor	Read-only runtime, API and login diagnostics; report format and recovery
maglev auth check	Current key metadata, without its secret
maglev discover --input discovery.json	Ranked matching capabilities
maglev inspect CAPABILITY_ID	Schema, requirements, evidence and price basis
maglev interviews start --kind founder	A founder interview; manufacturer is also supported
maglev interviews get INTERVIEW_ID	Saved questions, answers, extracted facts and version
maglev interviews answer INTERVIEW_ID --file answer.txt --version 0	Next interview turn, using the current version
maglev interviews confirm INTERVIEW_ID --version 1 --confirm	Confirm facts after reviewing them with the person
maglev quotes request --input request.json --idempotency-key request-001	Saved quote request; no supplier contact or order
maglev runs list	Most recent saved requests
maglev runs get RUN_ID	One saved request
maglev network summary	Directory coverage and provenance summary
maglev factories list --input filters.json	Paginated factory profiles; filters are optional
maglev factories get FACTORY_ID	Factory profile; contact access depends on key mode and scope
maglev knowledge search --input query.json	Relevant source excerpts
maglev knowledge read --input document.json	One source document with a live key
maglev lifecycle list	Manufacturing stages and availability
maglev lifecycle get STAGE_ID	Inputs, outputs and actions for a stage
maglev projects list	Recent projects accessible to this key
maglev projects create --input brief.json	Saved product brief, including your intent and unknowns
maglev projects get PROJECT_ID	Project and action counts
maglev projects update PROJECT_ID --input changes.json	Update selected project fields
maglev actions kinds	Current action names and input/output schemas
maglev actions list --input filters.json	Saved actions; optional project/status filters
maglev actions request PROJECT_ID --input action.json --idempotency-key action-001	Request a draft or coordinated task
maglev actions get ACTION_ID	Saved output, status and associated deliveries
maglev deliveries list --input filters.json	Delivery records; optional status filter
maglev deliveries get DELIVERY_ID	Message bodies and status for review
maglev context preview ./project	Local file manifest and hashes; no upload
maglev context review-bom bom.csv --mapping mapping.json	Local BOM review with exact cell values, source locations and questions; no key or upload
maglev context expand-bom bom.csv --mapping mapping.json --input plan.json	Exact assembly and purchase quantities from an explicit current-batch plan; no key, upload or purchasing authority

Data commands accept --json. login requires a human terminal; use environment credentials for automation. Run maglev --help for usage. Record IDs come from responses, not from filenames.

For CSV/TSV engineering exports, follow review a BOM locally. That command has a separate 2 MiB BOM limit, requires an explicit mapping, and refuses symlinks. It does not use the HTTP API.

Guided setup

Run from your project folder. A valid saved login or MAGLEV_API_KEY skips login. Otherwise setup displays a short code and opens your existing account’s browser connection page. Sign in as the organization owner, check that the browser code matches your own terminal, confirm the organization and mode, then choose Connect terminal. The key is saved privately and the CLI completes automatically. Approval permits API access with the displayed scopes; it does not approve supplier outreach, file disclosure or orders.

maglev login defaults to live. Use maglev login --sandbox for the synthetic catalog and demo; maglev setup --demo requests sandbox login when there is no valid existing connection. It refuses to run a demo with a live key. Use --no-browser to open the link yourself, or maglev login --key for hidden manual key entry. Non-owner members can use a key supplied through their organization’s approved process; browser pairing requires an owner.

Only one preference question remains: which agent to connect. Setup recommends the current agent when detected, otherwise your saved choice, an existing agent folder, then Claude Code. It does not ask where your files are or repeat the website’s company/profile questions. Tell the agent in natural language when your files live elsewhere.

Claude Code receives .mcp.json plus its project skill. Codex receives .codex/config.toml plus its project skill. Existing unrelated configuration is retained. A different existing Maglev configuration or customized skill stops setup for review. Repeated setup leaves identical files alone. Reopen your agent in the trusted project and accept its MCP connection prompt; configuration written by setup is not proof that the host has connected.

Other agents receive a credential-free stdio configuration to add in their MCP settings. Terminal-only setup writes no agent files. --directory remains an optional override. Setup does not scan or upload engineering files. The host agent handles file access and manufacturing questions when you ask it to do work.

For scripts, set MAGLEV_API_KEY or use an existing saved login, then run maglev setup --target codex --json. JSON mode never opens a browser, prompts, or emits animation, and defaults to terminal only if no target is provided. The example runs only with --demo or the separate maglev demo command.

Interrupted login

• Ctrl+C pauses the request. Rerun maglev login (or maglev login --sandbox) to resume the same connection. Do not delete the private pending record just to retry.
• Approval expires after ten minutes. Before the terminal acknowledges its durable save, the new key expires with that request. Once confirmed, live keys last ninety days and sandbox keys one day.
• A lost confirmation response reuses the saved key and acknowledgment. It does not issue another key. A declined or expired request can be started again.
• maglev login --cancel cancels an unfinished request, revokes its temporary key and restores the prior saved login if it has not changed. If the server already acknowledged the connection, rerun login to finish recovery, then revoke it from the developer console if needed.
• Two terminals cannot change the same profile at once. If a process crashed, wait one minute for its lock to expire before resuming.
• Network failures keep the private recovery record. A revoked/expired temporary key requires cancelling that unfinished request before a fresh login.

Login and preferences

~/.maglev contains an origin-specific credential file, an unfinished connection journal when needed, and a separate preferences.json with the chosen agent. Use MAGLEV_CONFIG_DIR for a different private directory. New directories/files use POSIX modes 0700/0600; Windows relies on the user’s directory ACLs. The private connection journal can retain the temporary credential and previous login until completion or cancellation. Keys are stored as local plaintext protected by those permissions, not in an OS keychain. Symlinked files, corrupt records and broad POSIX permissions are refused.

MAGLEV_API_KEY takes precedence over saved credentials, even when it is empty or invalid. Unset it to use maglev login. Credentials are bound to the exact normalized API base URL, so switching MAGLEV_API_URL cannot reuse a saved key for another service. The CLI and MCP read the same login; keys are never written to project config or skills.

maglev auth check --json reads current key metadata, mode, scopes and expiry from the API. It does not return a web user profile. Your company, workspace and onboarding answers remain managed in the web app. There is no second local business profile to keep in sync.

maglev logout removes this API’s local key. It does not revoke the key elsewhere or unset shell variables; revoke keys in the developer console. After expiry or revocation, run maglev login again. Login and setup support sandbox and live keys. Live setup connects the owner-authorized engineering tools and selected-file transfer tools; project, directory, action and delivery tools support live work; only the sample capability catalog and optional example remain sandbox-only.

Sandbox example state

maglev demo writes its synthetic request body, idempotency key and returned run ID under ~/maglev-example/, separated by API URL and sandbox key ID. It does not store the credential. Set MAGLEV_STATE_DIR to an existing writable directory to use another parent. New state files have owner-only permissions on POSIX systems; Windows uses the directory’s access controls.

The exact body and idempotency key are written before the request is sent. A repeated invocation retrieves the known run; after a lost write response it replays the same body/key before retrieval. It does not rerun discovery or create a fresh request merely because a response was interrupted. No matching example or unexpected response stops the flow without relaxing the request.

Keep the state directory after a timeout. If state is corrupted or changed, the CLI refuses to continue. Preserve it for review and inspect saved requests with maglev runs list; do not delete it merely to retry an uncertain write. An expired sandbox key cannot access its old sandbox records with a replacement key. A new key starts a separate example.

The example uses the hosted sandbox catalog and saves a synthetic quote request; no model-backed action, supplier contact or order is involved. The local walkthrough is a separate, key-free fixture demonstration.

Inputs and outputs

--input - reads JSON from stdin. --file - reads an interview answer as text. Unsupported top-level request and filter fields are rejected before transmission. Project intake is free-form context and is preserved. Action-specific input is sent unchanged: use the schema from actions kinds, since the server validates it and may discard unsupported fields. Input is limited to 64 KiB; API field limits also apply.

File paths must point to regular files; a link to a regular file is accepted. CLI 0.3.8 rejects named pipes and other non-file inputs before reading them, so an absent pipe writer cannot leave the command waiting. Use --input - or --file - for an intentional stdin stream; it waits for the producer to finish. The HTTP timeout starts with the request and does not time out stdin.

Files and piped input must use UTF-8. CLI 0.3.3 reports invalid_encoding and sends no request if it finds malformed bytes; export the source as UTF-8 before retrying. JSON may start with a UTF-8 byte-order mark. Valid Unicode text is preserved, including a literal � already present in the source.

CLI 0.3.7 rejects repeated property names within one JSON object with duplicate_key before HTTP. For example, a brief containing both "quantity": 100 and "quantity": 200 must be corrected instead of silently using the last value. Equivalent escaped names count as duplicates; the same field name in separate objects is valid.

CLI 0.3.7 also rejects NUL (U+0000) and unpaired Unicode surrogates in JSON values or property names, and NUL in interview text, with invalid_text before HTTP. Correct the source rather than deleting characters blindly. Valid emoji pairs, Chinese, literal backslash escape text and line breaks stay unchanged. This is a CLI input check; it does not claim the deployed API applies the same policy.

CLI 0.3.7 rejects numeric overflow, underflow to zero and whole-number values outside JavaScript’s safe integer range (−9,007,199,254,740,991 to 9,007,199,254,740,991). These return invalid_number before HTTP. Keep long part numbers and other identifiers as quoted strings. Ordinary numeric measurements use JavaScript floating-point precision; this is not arbitrary-precision decimal arithmetic.

discovery.json:

{"query":"CNC aluminum enclosure","quantity":100,"country":"US","optimize":"speed"}

maglev discover --input discovery.json --json > shortlist.json

Success is JSON on stdout; errors are JSON on stderr and use a nonzero exit code. --json emits a single compact JSON value without progress text. The API requestId and error.details are preserved, including a saved actionId or field validation messages when returned. Keys are redacted from output.

Exit code	Meaning
0	Success
1	API rejection or another failure
2	Invalid command, input or local file
3	Authentication or permission problem
4	Version or idempotency conflict
5	Rate limit, network failure, timeout or service failure

From a project folder to a draft

The synthetic example project includes a BOM, requirements, a brief and a strategy action. Your agent reads the local files with its existing tools, preserves their sources and unknowns in the brief, then calls Maglev.

maglev projects create --input brief.json --json
maglev actions kinds --json
maglev actions request PROJECT_ID --input action.json --idempotency-key revision-a-strategy-001 --json

Replace PROJECT_ID with the returned project.id. Review the current kind schema before preparing action.json. A generated strategy, NDA or engineering plan is a draft; its status and evidence determine the next step. See projects and actions.

projects update replaces the fields you provide. In particular, intake is replaced as a whole, so retrieve the project and merge its existing context before changing one intake item. A project edit does not alter prior action outputs.

The CLI supports exact delivery review, approval and recovery. Follow approved delivery execution; approval can send a real message and needs the principal’s authorization of that exact review.

Search filters

Factory filters use the network’s process taxonomy, which differs from catalog discovery. For example:

{"q":"CNC","region":"US","page":1,"pageSize":10}

answeredUs: true selects factories with a recorded response. Omit it to include all; false does not mean “unanswered.” Country/region preferences may produce no matches. Factory listings are directory records, not binding offers or a quality ranking.

For knowledge search, use {"q":"CNC tolerances","kind":"playbook"}. For knowledge read, use {"path":"EXACT_PATH_FROM_SEARCH"}; full documents require a live key. Query values are encoded by the CLI.

For actions list, use {"projectId":"PROJECT_UUID","status":"draft_ready"}. For deliveries list, use {"status":"draft"}. The API reference documents each endpoint’s limits and permissions.

Retrying safely

The CLI does not automatically retry writes. Follow idempotency and recovery to decide what to retry. Exit code 4 is a version or idempotency conflict.

Use --timeout 60000 to change the timeout; allowed range is 1,000 to 300,000 milliseconds. Action requests default to 240,000 milliseconds; other commands default to 45,000. Model-backed actions can take several minutes. Rate-limit responses preserve retryAfter when supplied.

Response handling

CLI 0.6.14 and MCP 0.2.14 use the same bounded response reader. Earlier hosted archives remain unchanged.

• API JSON responses may contain up to 2 MiB after decompression. The client counts received bytes, even if Content-Length is missing or inaccurate. Larger responses return response_too_large with details.limitBytes; no partial JSON is returned. Select a specific record, smaller page or narrower query where that endpoint supports it.
• Malformed UTF-8 returns invalid_response. The client does not silently substitute characters into document text or commercial terms. Valid Chinese, emoji and intentionally present replacement characters remain intact.
• The request deadline covers the response body. A timeout or interrupted stream returns network_error, preserving the available request ID, HTTP status and retry guidance. Reflected credentials are redacted from error metadata.

These response errors do not prove that a write failed on the server. Read the saved project, action, interview or delivery before trying again. Preserve its identifiers and original idempotency key where supported. The client never retries writes automatically.

Local file preview

maglev context preview ./hardware-project --json > manifest.json

The manifest lists relative paths, sizes and SHA-256 hashes for supported engineering/document file types. It does not parse the files or send them over the network. Sensitive/hidden names, generated directories and symlinks are excluded. Limits are 1,000 files, 100 MiB per file and 512 MiB total; skipped counts are returned. Review the manifest before any sharing.

API origin

The default is https://app.trymaglev.com/api/v1. MAGLEV_API_URL can select an explicitly configured HTTPS origin for development. Plain HTTP is limited to localhost. Authenticated redirects are refused to avoid forwarding credentials to a different destination.

Delivery commands

Command	Effect
maglev deliveries review ID --json	Exact current recipient/message review; sends nothing
maglev deliveries approve ID --input approval.json --confirm	Approves only the supplied review digest; can send a real message
maglev deliveries retry ID --confirm	Recovers the same approved frozen dispatch
maglev deliveries reject ID --input reason.json	Rejects a draft; cannot cancel a send already approved

Read delivery execution before approving. Project updates accept expectedContextVersion from the latest projects get response to prevent stale intent changes.

Engineering access

CLI 0.6.14 includes engineering get PROJECT_ID and engineering preview PROJECT_ID --input terms.json. See engineering access for owner grants, exact terms, API prerequisites and nonbinding result handling. Install the hosted 0.6.14 release; registry 0.5.1 lacks these commands.

Word evidence

context read-docx FILE.docx reads explicitly selected Word files locally. See Word evidence for selection, limits, confidentiality and unsupported content.

Supplier replies

CLI 0.6.14 / MCP 0.2.14 add read-only managed RFQ and supplier-submitted quote retrieval. See supplier replies for buyer permissions, version history and the distinction between a saved reply and permission to order.

Wait for new quote records

CLI 0.6.14 / MCP 0.2.14 adds a read-only wait for new supplier quote IDs on one owned RFQ. Quote waiting explains the explicit baseline, deadlines, cancellation, exact original records and error handling. Native connector 0.1.6 includes CLI 0.6.14/MCP 0.2.14 and can upgrade recognized original Claude Code/Codex projects after account connection. Custom configurations remain a local review case.

Observe saved actions

Wait for an action with hosted CLI 0.6.14/MCP 0.2.14. The bounded read follows an existing running action and returns original evidence at draft, approval, coordination or failure states. It never recreates work, retries a write or grants approval. Native connector 0.1.6 includes the same tools. Reconnect or review a project upgrade when using an older installation.

Recovering a lost action ID

Recover a lost action ID is available in hosted CLI0.6.14/MCP0.2.14. It uses the original project, kind and idempotency key, and reads only recent saved work. A missing match does not establish absence or authorize a replacement. Native connector 0.1.6 includes the same CLI 0.6.14/MCP 0.2.14 tools; an older project may need a reviewed upgrade.