Configuration
State on disk
The CLI keeps three separate things in XDG-standard locations:
| What | Path | Notes |
|---|---|---|
| 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-cliWhat 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 throughim-cli loginis 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
| Variable | Effect |
|---|---|
IM_CLI_API_URL | One-shot override of the active login's server (same as --api-url). Handy in CI. |
IM_CLI_TOKEN | Supply the PAT directly instead of reading the token store — the CI counterpart to an interactive login. |
IM_CLI_ALLOW_HTTP | Allow sending credentials to a non-loopback http:// server (otherwise refused). Only for trusted private networks. |
IM_CLI_NO_BROWSER | Don't try to open a browser during im-cli login — print the URL instead (same as --no-browser). |
IM_CLI_NO_UPDATE_CHECK | Disable the once-a-day update-check banner entirely. |
IM_CLI_ZIP_UPLOAD_MAX_KB | Override the client-side size ceiling im-cli push enforces before uploading. |
IM_CLI_DOWNLOADS_URL | The 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.