Skip to main content
Version: 3.x

Environment Variables

Mops CLI supports several environment variables to customize its behavior.

Network Selection​

MOPS_NETWORK​

Select the network (local, staging, or ic). This is the only way to change it — mops defaults to ic and never persists a network selection to disk, so every process that should talk to a different registry needs the variable set.

When set to local, the agent fetches the root key from the replica (required for local replicas) and defaults to http://127.0.0.1:4943.

note

Since mops 3.0.0 the agent makes update calls over the IC HTTP API v3 synchronous-call endpoint. A local replica has to serve it — icp and recent dfx do; a pre-v3 replica does not.

export MOPS_NETWORK="local"
mops install

Install Tuning​

MOPS_CONCURRENCY​

Cap the number of simultaneous registry requests during package installs (an integer ≥ 1). Applies to every command that installs packages — mops install, mops add, mops build, mops test, mops sources, and so on. Equivalent to mops install --concurrency <n>; the flag wins when both are set.

The default is derived from the CPU count (2 × cores, clamped to 4–16) and capped by the file-descriptor soft limit. Transient network failures retry on their own with the concurrency halved, but a low explicit value still helps environments that are constrained in ways mops cannot see — an egress proxy capping concurrent connections, for example:

export MOPS_CONCURRENCY=2
mops install

GitHub​

GITHUB_TOKEN​

Authenticate the requests mops makes to the GitHub API. It makes them to resolve a GitHub dependency's branch or tag to a commit (mops add org/repo, mops outdated, mops update, and mops install when neither mops.toml nor mops.lock names the commit), to look up toolchain releases (mops toolchain use <tool> latest, update, info and the version picker), and to read release notes in mops publish when CHANGELOG.md has no entry for the version.

Unauthenticated, GitHub allows 60 of these requests an hour per IP address, and a shared CI runner can start a job with that budget already spent. With a token they count against the token's own limit instead. It needs no scopes, since mops reads only public repositories. In GitHub Actions, pass the one the workflow already has:

- run: mops install
  env:
    GITHUB_TOKEN: ${{ github.token }}

The token is sent only to api.github.com, not with the archive downloads from github.com. A token GitHub rejects is not retried anonymously: the lookup fails, and a failed commit lookup names GITHUB_TOKEN in its error.

Project Environment​

MOPS_ENV​

Expanded into local path dependencies that contain the {MOPS_ENV} placeholder (defaults to local when unset):

[dependencies]
envdep = "./envs/{MOPS_ENV}/dep"
export MOPS_ENV="staging"
mops install

The lockfile stores the expanded path, so it is specific to the MOPS_ENV it was generated under — a lockfile generated under a different value counts as stale, and mops install --locked fails on it. See {MOPS_ENV} path dependencies.

MOPS_CWD​

Change the working directory before the command runs. Useful for npm scripts, where npm sets the working directory to the package root:

MOPS_CWD="canisters/backend" mops install

Registry Configuration​

MOPS_REGISTRY_HOST​

Override the registry replica or boundary node URL. Useful for pointing to a local IC replica or custom deployment during development.

export MOPS_REGISTRY_HOST="http://127.0.0.1:4943"
mops install

MOPS_REGISTRY_CANISTER_ID​

Override the registry canister principal. Use this to target a specific registry canister instance.

export MOPS_REGISTRY_CANISTER_ID="your-custom-canister-id"
mops install

Combined Usage​

Both variables can be set together to redirect all registry operations to a custom deployment:

export MOPS_REGISTRY_HOST="http://mops-alternative.host:4943"
export MOPS_REGISTRY_CANISTER_ID="2d2zu-vaaaa-aaaak-qb6pq-cai"
mops install

These overrides apply to all registry operations (add, install, publish, search, etc.) and work with any network selection (staging, ic, or local).

PocketIC​

MOPS_POCKET_IC_URL​

Connect to an already-running PocketIC server instead of spawning the [toolchain] pocket-ic binary. Applies to every Mops-managed PocketIC use: mops build --check-deploy, mops test --mode replica, mops bench, mops watch, and the tests and benchmarks mops publish runs.

Mops creates a PocketIC instance (POST /instances) for the run and deletes that instance when the command finishes — including on SIGINT. It never starts or stops the server process.

When this variable is set, a [toolchain] pocket-ic pin is ignored (Mops prints a warning) and the binary is not downloaded.

export MOPS_POCKET_IC_URL="http://127.0.0.1:8001"
mops build --check-deploy

The URL must be http or https and must speak the PocketIC control API, not the IC HTTP gateway. A malformed value fails every mops command with an error — broken environment config is rejected loudly rather than ignored.

Limitations of attached mode:

  • Canister log output is not streamed. Mops reads canister logs from the stderr of the server process it spawns; an attached server's stderr is out of reach, so mops test --mode replica shows per-file pass/fail but no test names and no Debug.print output (a warning is printed once).
  • Version compatibility is the operator's responsibility. Mops cannot check the remote server's version; keep the server on a PocketIC release compatible with the @dfinity/pic client bundled in your Mops version (9.0.0 or newer). An incompatible server surfaces as a connection or protocol error naming this variable.
  • mops bench records no replicaVersion in saved or published results, since the remote server's version is unknown (and the URL itself would leak environment details).