CLI Reference

The Almirant CLI lets you authenticate against one or more instances, link repositories to projects, and expose MCP to AI agents without writing tokens to project files.

Installation

npm i -g almirant

Verify the installation:

almirant version

Main commands

Command	Description
almirant login	Authenticate via browser and store an account in ~/.almirant/config.json
almirant accounts list	List configured accounts without showing secrets
almirant accounts rename <ref> <label>	Assign a human label to an account
almirant use [ref]	Select the active account; without an argument opens an interactive selector
almirant current	Show the active account without exposing the API key
almirant link	Link the current repository to a project using stored credentials
almirant init	Configure Almirant MCP for the current project (complete flow)
almirant mcp proxy --project-id <id> [--account <ref>]	Stdio proxy used by MCP agents; reads the token from local config

Accounts

almirant login can be run multiple times. Each account is stored with:

• a stable id for generated configuration;
• a local label for humans (local-m1pro, prod-saas, kroko-dev);
• email, API URL, and API key.

almirant accounts list
almirant accounts rename 2 local-m1pro
almirant use local-m1pro
almirant current

Commands that accept an account use <ref>: label, stable ID, unique email, or list index.

Generated files

File	Location	Description
config.json	~/.almirant/config.json	Local accounts and API keys; mode 600
.mcp.json	Repository root	Secretless MCP configuration that runs almirant mcp proxy
.claude/skills/	Repository root	Skills for Claude Code
.agents/skills/	Repository root	Skills for other agents

info

~/.almirant/config.json is the only local file that contains the API key and is written with 600 permissions. Do not share it or commit it.

Secretless MCP

almirant init and almirant link generate a stdio entry like this:

{
  "mcpServers": {
    "almirant": {
      "type": "stdio",
      "command": "almirant",
      "args": ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id>"]
    }
  }
}

The repository is pinned to a specific account via --account <account-id>, but contains no bearer tokens. The proxy reads ~/.almirant/config.json at runtime and attaches the token in memory.

For Codex .codex/config.toml, use the same proxy pattern:

[mcp_servers.almirant]
command = "almirant"
args = ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id-or-label>"]

To make the project follow the active account selected with almirant use, omit the --account ... pair. That is more flexible but less safe for old repositories because they may point to the wrong instance.

Migrating old token-based configs

Older configs used type: "http", url, and an Authorization: Bearer ... header. Replace them by rerunning:

almirant link

or manually switch the server entry to the stdio proxy above. If a real token was ever committed, rotate it from Almirant or with:

almirant config rotate api-key --account <ref>