Configuration

State on disk

The CLI keeps three separate things in XDG-standard locations:

WhatPathNotes
Active login$XDG_CONFIG_HOME/im-cli/config.json (default ~/.config/im-cli/config.json)The server API URL + a reference to the stored token. One active login at a time. Override the path with --config.
Token store$XDG_DATA_HOME/im-cli/tokens.json (default ~/.local/share/im-cli/)The PAT itself. Plaintext JSON at mode 0600 inside a 0700 directory (an OS keyring backend is planned; the file backend stays the fallback).
Update-check cache$XDG_CACHE_HOME/im-cli/ (default ~/.cache/im-cli/)Timestamp for the once-a-day new-version check. Safe to delete.

Per-project agent bindings are separate — they live in the gitignored .im/config.json in your project directory, keyed by server API URL (see the getting-started guide).

To wipe all local CLI state:

rm -rf ~/.config/im-cli ~/.local/share/im-cli ~/.cache/im-cli

What your token is allowed to do

A PAT carries abilities (agent-versions:read, agent-versions:write, external-agents:read, external-agents:write). They are a ceiling, not a grant: every request is authorised against your role in the organisation and the abilities of the token you presented, and the narrower of the two wins. A token can only ever reduce your reach — never extend it.

Two consequences worth knowing:

  • A token cannot mint a wider token. Creating a PAT while authenticated with one is refused (422) for any ability the presenting token does not already carry. Minting within its own abilities still works, so rotating a token is unaffected. Signing in through im-cli login is a browser flow, not a token request, so it is not subject to this — that is where a token with new abilities comes from.
  • Some actions are unreachable by any token. Anything that hands out a secret or changes who is in the organisation — rotating an org API key, inviting, removing or re-roling a member — is refused for every PAT regardless of its abilities, and has to be done in the Portal.

im-cli whoami reports the active server, the authenticated user and the linked agent. It deliberately does not print a permission list: authorisation is decided per request by the server, so a cached list on the client could only ever be a stale second opinion.

Environment variables

VariableEffect
IM_CLI_API_URLOne-shot override of the active login's server (same as --api-url). Handy in CI.
IM_CLI_TOKENSupply the PAT directly instead of reading the token store — the CI counterpart to an interactive login.
IM_CLI_ALLOW_HTTPAllow sending credentials to a non-loopback http:// server (otherwise refused). Only for trusted private networks.
IM_CLI_NO_BROWSERDon't try to open a browser during im-cli login — print the URL instead (same as --no-browser).
IM_CLI_NO_UPDATE_CHECKDisable the once-a-day update-check banner entirely.
IM_CLI_ZIP_UPLOAD_MAX_KBOverride the client-side size ceiling im-cli push enforces before uploading.
IM_CLI_DOWNLOADS_URLThe downloads host the update check reads (default https://downloads.mgt-platform.com). Point it at a mirror for an air-gapped install.

--api-url and --config (and the other global flags) take precedence over the environment when both are set.

The update check

Once every 24 hours the CLI reads releases/cli/index.json off the downloads host and prints a one-line hint to stderr if a newer release exists. It sends no credential — that index is the same public document the installer resolves against, and the same one a Portal installation polls — so the banner can never offer you a version you would not be able to install. It never blocks or fails the command you actually ran, it stays quiet when stderr is not a terminal (piped output and CI logs stay clean), and it will not offer a pre-release or a withdrawn build.

IM_CLI_DOWNLOADS_URL is deliberately the same variable the public installer reads: set it once and a machine installed from a mirror also checks that mirror, rather than being told to upgrade to something it cannot reach. The 24-hour cache is keyed by the index URL it was read from, so repointing at a mirror is not served a stale answer from the previous host.