Reference

What everything means

Sign-in with an API key or --clerk, workspace folders, privacy levels, assistant connections, guided migration, confirmations and error codes.

Updated November 2, 2026 · Terminal guides: CLI 0.7.0

This guide explains the ideas behind the netconverter commands: how you sign in, what a workspace folder is, what an AI assistant may see (exposure levels), how assistants connect, how a guided migration runs, and what each error means. Every command and flag is listed in the CLI reference; settings and environment variables are in COMMANDS.md; the data flow and threat model are in PRIVACY.md.

Sign-in and credentials

NetConverter accepts two kinds of credential. You need one of them; both work for the terminal, the app and the MCP bridge.

Where it is kept. In the operating system's credential store (macOS Keychain, Windows Credential Manager, Secret Service on Linux). Where none is reachable, or with --store file, in a passphrase-encrypted file (AES-256-GCM): set NETCONVERTER_CREDENTIAL_PASSPHRASE or NETCONVERTER_CREDENTIAL_PASSPHRASE_FILE. Never in plain text.

Which one is used. Plain commands use a stored API key first, then your sign-in. The MCP bridge (netconverter mcp) prefers the sign-in and says on stderr which key it leaves unused. Force one with --auth clerk|key (bridge) or NETCONVERTER_AUTH=clerk|key. One process always uses one credential for everything it does.

• netconverter whoami shows who is signed in and where the credential is kept; it never prints a token.
• netconverter logout removes the sign-in; logout --all also removes the stored API key.
• netconverter capabilities (or allowance) shows the vendors, conversion paths, job types and limits your credential has.
• A 0.1.x Terminal Quick pilot key reaches only the pilot profile (ASA → Palo Alto, 50 KB); it has no prescan.

Workspace folders

Everything the terminal reads or writes stays inside one workspace folder: the current folder, or the one given with --workspace DIR (a global option, before the command). Paths outside it, symbolic links that leave it, and the .netconverter/ state folder are refused. The state folder keeps the active job, the bridge activity log (paths, sizes, hashes and job ids only) and the folder's privacy setting.

--server URL chooses the NetConverter API (default https://api.netconverter.ai/external/v1). Use a dedicated folder per migration project, for example ~/migrations, not your home folder.

Privacy and exposure levels

Your configuration files never go through an AI model: the bridge reads the file and uploads it directly to NetConverter. What an assistant does see are the results: summaries, findings, decisions. The folder's exposure level decides how much of them.

• Secrets are removed at every level (pre-shared keys, SNMP communities, password hashes), by the server and again by the bridge.
• The server view. NetConverter's MCP server has two views: default (your tenant's own addresses and names) and strict (tokens and masks, no configuration-content tools). The bridge sends the level on every request; the server applies the lower of your grant and the level. The strict view lists no guided-migration tools and no write tools, so a guided migration needs full.
• Why raising needs a typed confirmation. netconverter privacy level full asks you to type raise to full in a terminal. It refuses without a terminal, so no script, AI assistant or MCP tool can widen what an assistant sees. Lowering needs no confirmation. Every change is recorded in .netconverter/privacy-audit.jsonl.
• Per process. netconverter mcp --level LEVEL (or --strict, or NETCONVERTER_MCP_VIEW) can only lower the folder's level for one bridge process; --full works only once the folder is at full.
• netconverter privacy status shows the level and recent changes; privacy apply --client … keeps an assistant's own file-reading tools out of the folder, so it works on your configurations only through the bridge.

After you change the level, restart (or reconnect) the assistant: assistants keep the tool list they read when they started.

AI assistants and the MCP bridge

An AI assistant reaches NetConverter in one of two ways:

netconverter connect shows the exact change it makes and asks first; JSON settings files keep a .bak. If the assistant already has a netconverter entry, connect shows it instead of changing it: edit its --workspace argument yourself.

ChatGPT. The ChatGPT desktop app's agent runs MCP servers from ~/.codex/config.toml, the same file Codex CLI uses, so netconverter connect codex in your folder connects it; restart ChatGPT afterwards. Step by step: connect/chatgpt.md.

Bridge tools. Local: submit_file, job_status, wait_for_job, account, download. Proxied from NetConverter (only from a fixed list in the client, and only what the server offers to your account at your level): reports, evidence, NAT, routes, flows, objects, the knowledge base, guided mapping (get_mapping_questions, validate_mapping, apply_mapping_answers), guided migration (list_operations, get_decision_document, validate_decision_document, propose_operations, submit_conversion) and set_view_level. The full list is in COMMANDS.md. account says which guided tools this session has and, when they are hidden, why.

Write tools. propose_operations, submit_conversion and apply_mapping_answers create work. The server lists them only in the default view (level full) and only for tenants where a NetConverter administrator enabled them; it checks and audits every call.

Job types

Vendor codes (cisco_asa, palo_alto_xml, fortinet, …) and the supported paths come from netconverter capabilities.

Guided migration (prescan, decisions, conversion)

A guided migration lets you decide how each item is handled before anything is converted. Ask your assistant, for example: "Prescan ~/migrations/edge.cfg from ASA to Palo Alto XML and walk me through the decisions."

1. Prescan. submit_file(path, source_vendor, target_vendor?, job_type="prescan") uploads the file; the job gets a psc_ id and stops. wait_for_job until it is completed.
2. Read the decisions. list_operations (what can be decided), get_decision_document (the current revision and its sha256) and validate_decision_document, each with job_id=psc_….
3. Decide. The assistant asks you about each item; it must not choose skip for you. propose_operations(job_id, changes, base_sha256) records your choices as a new revision.
4. Convert. With your OK, submit_conversion(job_id, revision) queues the conversion as a new tra_ job (the assistant confirms with you first, see below).
5. Results. wait_for_job, then get_job_brief / get_evidence, and download saves the translated configuration, the report and the evidence workbook in the folder, hash-verified.

Needs: a credential that can submit jobs (sign-in, or an API key with write:jobs), the folder at exposure level full, and the write tools enabled for your tenant. Without the write tools you can still prescan and read the decisions, then convert in Quick Convert or Conversion Studio.

Confirmations before an upload or a conversion

Before submit_file uploads a file, and before submit_conversion or apply_mapping_answers queue a conversion, the bridge asks you:

• Assistants that show forms (MCP elicitation): a dialog with the path, size and SHA-256 (or the job and revision). Accept sends it; Decline or closing the dialog sends nothing (upload_declined / apply_declined).
• Assistants that cannot show the form (ChatGPT, Claude Code and others answer it automatically, unseen): the bridge sends nothing and answers confirmation_required with a single-use confirm_token for that exact call (valid 10 minutes). The assistant must ask you in the conversation; only after your yes does it repeat the call with the token.
• No forms at all: netconverter mcp --no-upload-confirm (or NETCONVERTER_MCP_UPLOAD_CONFIRM=0) relies on the assistant's own tool-approval prompt only.

Updating

netconverter update --check says whether a newer release exists; netconverter update installs it (with uv, from PyPI, or the verified GitHub release). Then restart your AI assistants so they start the new bridge and read its tool list again.

Error codes and what to do

Bridge and server errors come back to the assistant as a JSON object with error (the code) and message.

More symptoms (installation, keyring, file size, proxies) are in COMMANDS.md § Troubleshooting.

Source and release context: GUIDE.md · Privacy and data flow