CLI

One entry point, meshie, with two halves: commands that read a snapshot on disk, and meshie remote, which runs the same queries against a hosted workspace. Both print for a person by default and take --json for everything else.

Install

uv tool install git+https://github.com/cr-digital-services/meshie.git
uv tool install "meshie[remote] @ git+https://github.com/cr-digital-services/meshie.git"

The remote commands need the extra; the local ones do not.

Local commands

These read a snapshot you built yourself, from a Salesforce metadata directory on disk. No workspace, no account, no network.

Command	What it does
Command`meshie scan --source <sfdx-root>`	What it doesBuilds the graph and caches it, by default to `.meshie/snapshot.json`. Add `--target-org <alias>` to also run the live pass against a connected org.
Command`meshie impact <node-id>`	What it doesWhat breaks if this node changes. The flagship command.
Command`meshie unused`	What it doesFields with no inbound reference anywhere in the graph.
Command`meshie report --out report.html`	What it doesA self-contained HTML audit report, one file, no assets to host.
Command`meshie ask "..."`	What it doesOne-shot grounded chat, the same engine the in-app assistant uses. Needs `ANTHROPIC_API_KEY`.
Command`meshie mcp`	What it doesThe MCP server over stdio, for Claude Code, Cursor or any MCP client, reading the same snapshot. Needs the `mcp` extra; see MCP server. Blocks, no `--json`.
Command`meshie serve`	What it doesThe optional local viewer (needs the `viewer` extra). No `--json`: it blocks rather than returning a result.

Remote commands

meshie remote runs the same queries against a workspace, so a script does not need a local copy of the metadata at all.

meshie remote login --token <secret> --workspace <slug> --api-url https://meshie.ai

The token comes from the workspace’s Settings, CLI tokens page, and is shown once at creation. Creating one requires the Pro plan; every local command above works on any plan with no token at all. In CI, set MESHIE_API_TOKEN and MESHIE_WORKSPACE instead of logging in: the environment takes precedence over the stored credentials file, so a checked-out workspace with no home directory works the same way.

remote whoami, remote search, remote impact, remote unused, remote ask and remote retrieve are the hosted equivalents. They call the same routes the web app calls, so the CLI and the product cannot drift apart.

JSON output

Every command that returns a result takes --json. In that mode stdout is one JSON document and nothing else: no headings, no notes, no warnings. Anything the human listing says in prose becomes a field.

meshie impact salesforce:CustomField:Account.Status__c --json | jq '.direct_references | length'

Two shapes are worth knowing before you script against them:

impact --json emits target_id, reachable_from_unknown, direct_references, affected_by_system, depth, field_references_tracked and coverage (the checked / not-checked strip, see the impact query). Those are the hosted API’s own field names, minus the deep links only the server can build, so impact and remote impact hand you one shape rather than two.
unused --json emits the whole finding, risk_note and evidence included, not just the node ids the human listing prints. Read the risk note before you delete anything.

Failures stay plain text on stderr in both modes. The exit code, not stdout, is the machine-readable failure signal.

Exit codes

Code	Name	Means
Code0	NameOK	MeansThe command ran and the result is on stdout.
Code1	NameERROR	MeansNo cached snapshot, a missing optional extra, an unset API key, nothing detected to scan.
Code2	NameUSAGE	MeansA bad command line. argparse's own code; no command returns it.
Code3	NameNOT_FOUND	MeansThe command ran and the thing asked about does not exist: a node id that is not in the graph, an email with no user.
Code4	NameAUTH	MeansNot logged in, or the workspace rejected the token.
Code5	NameUNVERIFIABLE	Meansimpact only: the target is reachable through an UNKNOWN edge.

3, 4 and 5 are the reason this table exists. A missing node, a bad token and an unverifiable answer all used to exit 1, so a script could only tell them apart by matching on the message.

One asymmetry to know about: a remote command against a workspace that has never scanned exits 3, because the API answers that case with a 404. Its local twin, run with no cached snapshot file, exits 1. The message on stderr is what distinguishes them.

Wiring it into CI

A gate that should fail on either a real error or an unverifiable answer:

meshie impact "$FIELD" --json > impact.json || exit $?

One that accepts an incomplete answer but still fails on a real error:

meshie impact "$FIELD" --json > impact.json
status=$?
[ "$status" -eq 0 ] || [ "$status" -eq 5 ] || exit "$status"

The CI gate guide puts this in a full workflow.

Where credentials live

MESHIE_API_TOKEN, MESHIE_WORKSPACE and MESHIE_API_URL in the environment, each overriding the file independently.
Otherwise the credentials file written by remote login. Remove it with meshie remote logout.

A token is scoped to one workspace and to the user who created it, and carries that user’s role. Revoke it from the same Settings page; revocation takes effect on the next request.