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 versionThere 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.3Check 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-anchorIf 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/apiPrefer 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-agentTwo starters today (the SDK is Python-only):
| Template | What it is |
|---|---|
python-blank | Zero-dependency stdlib agent that echoes its input. The quickest path to a working run — no resource grants needed. |
python-llm | Calls 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.
4. Link to a Portal agent
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 separateim-cli initstep: linking is the single entry point. To inspect what the agent may call, runim-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_reviewim-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=helloRun 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 immediatelyim-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 runsim-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.
modelsandservicesare separate grants, and only one of them is obvious. Granting theopenaiservice 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 whileim-cli agent modelsreturns[]— 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 pushto 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 backThere 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
| Symptom | Cause / 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 run | Nothing's been pushed. Run im-cli push first. |
im-cli run exits non-zero | The run failed at runtime — read the streamed console output (or im-cli logs <execution>) for the error. |
token rejected — run im-cli login | The PAT expired or was revoked. Re-authenticate. |
Full flag reference for any command: im-cli <command> --help, or the
Commands page.