Getting started

im-cli is the developer CLI for the in·manas Portal. It takes you from an empty folder to a running agent: scaffold a starter, link it to a Portal agent, push your code as a version, and run it — streaming the output in your terminal.

1. Install

One command, on macOS, Linux, WSL and CI runners alike:

curl -fsSL https://downloads.mgt-platform.com/install.sh | sh
im-cli version

There is no credential anywhere in that line, and that is the point: im-cli is published to a public downloads host where discovery is a static index.json anyone may read and the archives sit beside it. A CI job installs the CLI with exactly the command a laptop does — nothing to create, paste, rotate or leak. (The GitLab installer that wanted a personal access token is retired: the package registry it downloaded from is no longer written, and personal access tokens are being withdrawn for CLI distribution entirely.)

What the script does before it puts a binary on your PATH: it picks the newest release that is neither a pre-release nor withdrawn (a withdrawn build is refused by name, with the reason it was pulled), verifies the release signature against the key pinned inside the script, checks the archive's SHA-256 against the signed checksum manifest, and only then extracts to $HOME/.local/bin/im-cli. Add that directory to your PATH if it isn't already — the script prints the exact line if it isn't. --bin-dir <path> installs elsewhere, and --version 1.2.3 pins a build, which is also the only way to get a pre-release:

curl -fsSL https://downloads.mgt-platform.com/install.sh | sh -s -- --version 1.2.3

Check it: im-cli version. Diagnose your setup any time with im-cli doctor — it reports the CLI, your login, and whether this machine has the Python and uv an agent project needs, naming the command that fixes each one it cannot find. Upgrade later with im-cli upgrade, which verifies the new release against the key compiled into the binary you are already running. Re-running the install command upgrades too, and is what to use on a build that predates im-cli upgrade — it replaces the existing binary in place.

The signing key, and how to check it

Every release is signed by one key. Its fingerprint is:

SHA256:EZR/TRns1n4X3r2MP7M8CzmHqD1fHKlxzlRDBV/1mEQ  release@in-manas.com

install.sh carries that key inline and im-cli has it compiled in, so neither of them asks the downloads host which key to trust. That matters more than it sounds: a verifier that fetches its own trust root from the host it is verifying would accept anything that host chose to serve, because an artifact, its signature and the anchor can all be replaced together and still agree.

Read this page from the Portal, or the repository README, when you are checking a fingerprint. A copy of these docs is also mirrored onto the downloads host at /docs/, and that copy is not an independent source: a host that had been tampered with would serve a fingerprint matching whatever it was signing with. The value of the string below is that it exists somewhere that host does not write. Compare it with what your binary pins:

im-cli version --trust-anchor

If those two strings match, the binary you have verifies releases against the same key we sign them with. If they do not, do not upgrade with it, and tell us. More than one key listed means a key rotation is in its overlap window, which is normal and deliberate: the new key is shipped in a release before anything is signed with it, so no installed CLI is ever stranded by the switch.

im-cli upgrade and im-cli version --trust-anchor both arrived with the pinned key, so a build installed before it answers unknown command. Re-run the installer to get one that has them; the fingerprint above is what it will print.

2. Sign in

im-cli login --api-url https://portal.example.com/api

--api-url is optional — it defaults to http://localhost/api (the local dev stack), so im-cli login alone signs in locally. Pass --api-url for a remote.

This opens your browser to the Portal's CLI authorization page. Confirm the code, and the CLI receives a personal access token (PAT) and records the active login (the server's API URL + token reference) under ~/.config/im-cli/config.json. There's a single active login at a time — after this you never pass --api-url again; later commands use the stored login.

Authorizing always requires a fresh sign-in (and 2FA if your account has it), even if you're already logged into the Portal — it's minting a long-lived token, so it's treated like a sensitive action.

For CI / headless machines, skip the browser:

echo "$CI_PAT" | im-cli login --with-token - --api-url https://portal.example.com/api

Prefer stdin (--with-token -) or the IM_CLI_TOKEN env var over passing the token as a flag value — command-line arguments leak into process lists, shell history, and CI logs.

3. Scaffold a starter

im-cli new                       # list the public template catalog
im-cli new python-blank my-agent # extract a starter into ./my-agent
cd my-agent

Two starters today (the SDK is Python-only):

TemplateWhat it is
python-blankZero-dependency stdlib agent that echoes its input. The quickest path to a working run — no resource grants needed.
python-llmCalls an LLM through the in·manas SDK. Needs an llm model alias granted to the agent.

Each starter substitutes {{name}} from the directory name (or --var name=…) and ships a .im/io.json declaring the agent's typed inputs/output.

An admin creates the agent in the Portal and grants it the models and services it may use. You then bind your project to it:

im-cli link --agent <agent-uuid>

im-cli link creates the .im/ scaffold (config.json + an io.json skeleton

  • a .im/.gitignore) if it doesn't exist and derives your organization automatically from the agent. There is no separate im-cli init step: linking is the single entry point. To inspect what the agent may call, run im-cli agent models / im-cli agent services — both query the Portal live, so there's no local manifest snapshot.

The .im/config.json it writes is a local, gitignored file that maps the server's API URL to its agent binding — so the same project can be linked to a different agent on each Portal; im-cli link adds an entry for your active login's server rather than overwriting the others. Pass --org <uuid> only to disambiguate when the agent could belong to several of your orgs. io.json stays tracked — commit it.

5. Push a version

im-cli push            # zip the project, upload as a new draft version
im-cli push --submit   # …and transition it straight to pending_review

im-cli push zips the current directory (skipping node_modules, .git, .venv, __pycache__), uploads it, and the server stamps the version label (v1, v2, …). Without --submit it lands as a draft you can iterate on.

The trip back is im-cli pull: it downloads a version's source and unpacks it, which is how you populate a fresh clone from a live agent or check a portal against what's in git.

6. Run it — including drafts

im-cli run --input message=hello

Run this from your project folder — im-cli run takes the agent from .im/ (no UUID needed). By default it runs the latest runnable version (the draft you just pushed), so you can iterate without publishing:

im-cli agent versions          # versions + which you can run + each version's inputs/output
im-cli run 2                   # run a specific version_number
im-cli run --detach            # print the execution UUID and return immediately

im-cli run streams the run's console output — timestamped, colour-coded log lines, the same you'd see on the Portal's Console tab — and exits 0 when the run succeeds, non-zero when it fails or is cancelled. (Piping the output gives you raw NDJSON instead, for scripting.)

Which versions you may run depends on your role and the version's status: developers run their drafts, reviewers run pending-review versions, anyone runs published ones. CLI runs are tagged with the cli execution source.

7. Inspect

im-cli agent models      # the model aliases this agent may call (don't guess names — query these)
im-cli agent services    # the connected services it may use
im-cli logs <execution>  # replay an execution's console output; --follow to stream
im-cli execution list    # recent runs

im-cli agent models / services are the ground truth for what your agent is allowed to use — the admin defines these grants in the Portal; you read them here (and so does any AI assistant generating agent code).

Two things worth knowing about the answer:

  • An empty list means the agent is granted nothing, not "no restrictions". A new agent starts with nothing and denies every resource call until an admin grants it something, so an empty result is the explanation for a run that fails on its first call.
  • models and services are separate grants, and only one of them is obvious. Granting the openai service does not give the agent a model alias: core.llm.call(alias=…) reads the first list, core.services.* the second. An agent can therefore show every provider connected and active while im-cli agent models returns [] — it looks fully provisioned and fails on its first LLM call. If a run dies there, read both lists before anything else.
  • The answer is live. A grant an admin changes in the Portal applies to your agent's next run — there is no need to im-cli push to pick it up. A run already under way keeps the permissions it started with.

Switching servers (staging / prod / multiple orgs)

The CLI keeps a single active login — one server at a time. Most people only use one Portal. To switch, just log in again — the new login replaces the active one:

im-cli login --api-url https://staging.example.com/api   # staging is now active
im-cli whoami                                            # shows the active server + linked agent
im-cli login --api-url https://portal.example.com/api    # switch back

There are no named contexts. For a one-off against another server (chiefly CI), override per command with --api-url <url> / IM_CLI_API_URL (and IM_CLI_TOKEN for the PAT) — that doesn't change the stored login. A project's per-server agent bindings live in .im/config.json (see step 4), keyed by server URL.

Troubleshooting

SymptomCause / fix
refusing to send credentials over plaintext http …The API URL is http:// to a non-loopback host. Use https://, or set IM_CLI_ALLOW_HTTP=1 for a trusted private network.
This agent has no runnable version yet on im-cli runNothing's been pushed. Run im-cli push first.
im-cli run exits non-zeroThe run failed at runtime — read the streamed console output (or im-cli logs <execution>) for the error.
token rejected — run im-cli loginThe PAT expired or was revoked. Re-authenticate.

Full flag reference for any command: im-cli <command> --help, or the Commands page.