ingot CLI reference

Every command and option of ingot, the command-line tool that scaffolds, validates, packages and publishes Ingot store extensions (package @ingotide/cli, Node.js 22 or newer).

npm install -g @ingotide/cli     # or: npx @ingotide/cli <command>
ingot help
ingot <command> --help

Commands

CommandWhat it does
ingot init [folder]Scaffold an extension: ingot.json, README, CHANGELOG, LICENSE, .gitignore, starter files and a CI workflow
ingot add <kind> <name>Add a rule, habit, command or MCP server: the file and its ingot.json entry
ingot try <project>Install the extension into a project's .ingot/ folder to test it
ingot validateCheck ingot.json and every file it points at, like the store does
ingot packageWrite <publisher>.<name>-<version>.ingotx
ingot loginCheck a publish token and save it
ingot logoutForget the saved token
ingot whoamiShow the publisher and expiry of the token in use
ingot publish [file]Upload to the store
ingot unpublish [id]Remove a version or the whole extension
ingot version [bump]Print versions, or bump the version in ingot.json
ingot exportWrite .ingot/rules to AGENTS.md, CLAUDE.md, .cursor/rules, .windsurf/rules and the Copilot instructions; --check for CI
ingot rules testRun .ingot/tests/*.yaml against your rules with a cheap model under a hard cost cap
ingot rules pruneList stale rules (unused, dead globs, deleted paths, removed packages); --apply removes them
ingot reviewAgent review before commit: the staged changes (else all), in a review mode (--mode) or as Find issues (--find-issues), with findings, fixes and a hard cost cap; exits 1 on high-severity findings
ingot tab predict <file>Show the ghost text and next edit Tab would suggest at --line, with a cheap model under a hard cost cap
ingot context files|attach|compose|rules|projectsWhat the agent chat attaches: every project file ranked like the @ picker, the context a chip sends, the prompt a typed message sends (chips in typed order), the / menu's rules and the /projects/ list. No model is called
ingot learningsShared project context: what agents and teammates learned about the project in .ingot/context. list, add, share, outdated, remove, what an agent gets (prompt), check for CI and sync to AGENTS.md. No model is called
ingot image notes <image>Ask a vision model about an image; it points at parts of it with numbered notes and writes an annotated SVG, under a hard cost cap
ingot merge <yours> <base> <theirs>Smart merge, like the diff viewer: non-conflicting changes applied, conflicts left as markers; exits 1 while conflicts are left
ingot handoff sendSend a task or a plan to an Ingot cloud agent on the project's GitHub repository; list, status, cancel, followup and checkout follow up on its runs
ingot preview servers|devices|checkThe App Preview from the terminal: local dev servers and web pages like its port menu, the device sizes, and whether a port or URL answers (--wait for scripts). No model is called
ingot preview mobile, ingot preview qrMobile preview from the terminal: iOS Simulators, iPhones, Android emulators and phones, open a dev server or Expo app on one, connect Android over Wi-Fi, and a QR code of the LAN address. No model is called
ingot usageToken units left, usage per model tier, Zaprex minutes; turn on-demand on or off with a cap; team member caps
ingot agentsThe Agent Command Center in the terminal: the agents of every Ingot window on this machine and your cloud agent runs, by status; cancel stops a cloud run
ingot automationsAgents started by a PR, comment, CI failure, Slack, webhook or schedule that hold a goal until met: list, validate, new, test offline, sync to the cloud, run and fires
ingot acpOpen-source agents (OpenCode, Goose, OpenHands) or any Agent Client Protocol agent you add, from the terminal: list them, check the handshake, run one turn, add a custom agent
ingot arenaArena mode in the terminal: two hidden models answer one task under a hard cost cap, you vote, then the models are revealed; vote, leaderboard and votes read and write .ingot/arena/votes.jsonl
ingot extensionsIngot store extensions such as the Agent Command Center: list with price and tier, info, install, uninstall, and turn the in-app feature suggestions on or off
ingot panesSession Panes: plan up to 8 agent sessions in .ingot/panes.json for Ingot to open side by side. list, add, remove, clear, layout, validate for CI and grid to preview a layout. No model is called
ingot layoutFocused agent layout: show each layout setting with the file it comes from, set or reset one in the project, user or global settings file, and list them all. No model is called
ingot sandboxAgent Sandbox: which OS sandbox agents get on this machine (Seatbelt, bubblewrap or the Windows approval gate), and the project allow-list of commands, hosts and folders in .ingot/policy.json. status, list, allow, remove and wrap to print the sandboxed command line. No model is called
ingot gitGit hosts: connect GitLab, Bitbucket Cloud and Data Center, Azure DevOps, Gitea or Forgejo with a token or OAuth, list repos, branches, pull requests, issues and CI runs, open a pull request or issue, and mcp serves the same tools to agents
ingot mcpMCP servers: list the servers in mcp.json, sign in to remote servers with OAuth, check their health (exit 1 when one is down), list tools with their risk and call a tool
ingot extensions search|install|inspect|sourcesMarketplace search: one list from the Ingot Store and Open VSX (the Microsoft Marketplace only with --microsoft-marketplace), install a .vsix by id or file into Ingot's extensions folder, inspect a .vsix. Short form ingot ext
ingot habitsHabits: the typed knowledge folder .ingot/habits/ (bug.md, tests.md, …). init, add (classified or --type), classify, read, relevant, new-type (or new type <name>), list, show and the scenario playbooks (new playbook <name>). No model is called

Most commands take --cwd <dir> to work on another folder, and --help.

init

ingot init [folder] --type <theme|rules|habits|mcp|rex-template> [options]
OptionDefaultNotes
--typeaskedthe extension type
--namethe folder namelowercase words joined with -
--publisheraskedyour publisher handle
--display-namefrom the nameshown in the store
--descriptionper typeone line for the store card
--licenseMITan SPDX id; an MIT LICENSE file is written
--cigithubgithub (.github/workflows/ingot-publish.yml), gitlab (.gitlab-ci.yml) or none
--forcewrite into a folder that isn't empty
-y, --yesnever prompt; use defaults

Without --yes, missing values are asked interactively. In CI (no terminal, or CI set) nothing is asked.

add

ingot add rule <name> [--description <text>]
ingot add habit <id> [--title <text>] [--match <regex>] [--rule <text>]
ingot add command <name> [--description <text>]
ingot add mcp <id> --command <cmd> [--env NAME=description]... [-- <args>...]
ingot add mcp <id> --url https://...

Arguments after -- are passed to the MCP server command, so flags like -y reach it: ingot add mcp acme --command npx -- -y @acme/mcp.

try

ingot try <project-folder> [--cwd <extension-folder>]

Copies the package to <project>/.ingot/extensions/<publisher>.<name>/, rules to .ingot/rules/, commands to .ingot/commands/, and merges MCP servers into .ingot/mcp.json. Run it again after each change.

validate and package

ingot validate
ingot package [--out <file>]

Both run the store's checks (manifest fields, file paths, file contents, Habits patterns, theme JSON, limits). package then writes the .ingotx and prints its files and SHA-256.

login, logout, whoami

ingot login [--token <token>] [--registry <url>]
ingot whoami
ingot logout

login checks the token with the store and saves it in ~/.ingot/cli/credentials.json (mode 600). Set INGOT_CLI_HOME to keep it somewhere else. In CI, skip login and use INGOT_PUBLISH_TOKEN.

publish

ingot publish [package.ingotx] [--token <token>] [--registry <url>] [--no-package]

Without a file, it packages the current folder first. --no-package uploads the .ingotx that ingot package already wrote for the current version (CI does this so the uploaded file is the one it built and kept as an artifact).

unpublish

ingot unpublish [publisher.name[@version]] [--version <x.y.z>] [--yes]

Without an id it uses ingot.json in the folder. Without a version it removes every version. It asks you to type the name to confirm; --yes is required when nothing can be asked (CI).

version

ingot version                    # CLI version and the extension's version
ingot version patch              # or minor, major, or an exact version like 2.0.0-beta.1

Sets version in ingot.json and adds a heading to CHANGELOG.md. Then commit, tag and push (git tag v1.2.3).

Project rules

export and rules work on a project's .ingot/rules, not on an extension. Run them in the project folder or pass --cwd.

npx @ingotide/cli export --check          # CI: fail when exported files drift
npx @ingotide/cli rules test --mock       # CI: rule tests with the free mock model
npx @ingotide/cli rules prune             # dry run; add --apply to change files

Every option is on Export rules, Rule tests and Prune stale rules.

Images

image notes sends an image to a model that reads images, gets numbered notes back (boxes, arrows, pins, text) and writes an annotated SVG next to the image.

npx @ingotide/cli image notes screenshot.png --prompt "Is the header aligned?"   # default model, $0.01 cap
npx @ingotide/cli image notes screenshot.png --mock --json                        # CI: the free mock reply

Every option is on Image notes.

Review before commit

review runs the IDE's Agent review on the staged changes (all changes when nothing is staged), in a git hook or in CI:

npx @ingotide/cli review --staged         # pre-commit hook: exit 1 on a high-severity finding
npx @ingotide/cli review --apply          # write the suggested fixes into the files
npx @ingotide/cli review --mode both      # your project rules plus the industry checklists
npx @ingotide/cli review --find-issues    # deeper bug hunt that reads the whole changed files
npx @ingotide/cli review --mock --json    # free, deterministic mock reviewer for testing pipelines

Every option is on Agent review before commit.

Tab

tab predict sends the prompt Tab sends in the editor (the code around the caret plus a few nearby files) and prints the prediction. Files matched by .ingot/ignore are never read.

npx @ingotide/cli tab predict src/app.ts --line 12     # default model, $0.01 cap
npx @ingotide/cli tab predict src/app.ts --mock        # CI: the free mock model

Every option is on Tab completion.

Diff and merge

merge runs the diff viewer's smart merge on three files: every change only one side made (or both made the same way) is applied to the base, and each conflict is left as diff3-style markers, or resolved with --conflicts yours|theirs|both.

npx @ingotide/cli merge yours.ts base.ts theirs.ts                   # print the result; exit 1 while conflicts are left
npx @ingotide/cli merge yours.ts base.ts theirs.ts -o yours.ts --json # write it, print {conflicts, merged, sameLine, chunks}
git config merge.ingot.driver "ingot merge %A %O %B --output %A"     # use it as a git merge driver

--label-yours and --label-theirs set the names after <<<<<<< and >>>>>>> (default: the file paths).

When both sides edited the same line but different tokens, the line is merged token by token, as in the viewer (sameLine in --json). --line-only merges whole lines only, like git: any line both sides edited is a conflict.

Chat context

context shows from the terminal what the agent chat attaches. Nothing is sent to a model and nothing leaves your machine.

npx @ingotide/cli context files crt                     # src/cart.ts: the @ picker's fuzzy filter
npx @ingotide/cli context attach src/cart.ts:1-2 docs @api-style   # the blocks the chat sends
npx @ingotide/cli context rules                         # Project rules, then User rules
npx @ingotide/cli context compose "explain lines 20-21 of @src/cart.ts"   # the prompt the chat sends, chips in typed order
npx @ingotide/cli context files helper --project other-app        # a file from a recent project, absolute path

Every option is on Drag, paste & @ files, @opens, @pins, / rules & /projects and Inline chips in the chat.

Shared project context

learnings works with the shared project context in .ingot/context/, one Markdown file per learning. add confirms a learning that is already there instead of copying it, and replaces anything that looks like a secret with [redacted]. list --status stale shows learnings whose paths are all gone. check exits 1 on bad file names, unknown topics or statuses and secrets, and warns about stale learnings and near-duplicates. sync writes the AGENTS.md block for other coding agents; sync --check exits 1 when it is out of date.

npx @ingotide/cli learnings                                     # proposed first, stale flagged; --status, --topic, --json
npx @ingotide/cli learnings add "[test] Run e2e with npm run e2e (paths: e2e/)" --propose
npx @ingotide/cli learnings prompt "fix the users endpoint" --files src/api/users.ts   # exactly what an agent gets
npx @ingotide/cli learnings outdated test-run-e2e-with-npm-run-e2e-k3f9 --reason "renamed to test:e2e"
npx @ingotide/cli learnings check && npx @ingotide/cli learnings sync --check           # in CI

Cloud agents

handoff hands a task to an Ingot cloud agent, which works on the GitHub repository and opens a draft pull request. It needs a personal access token (ingot_pat_…) in --token or INGOT_TOKEN:

ingot handoff send --prompt "Add CSV export to the reports page" --watch   # follow the run until its PR opens
ingot handoff send --plan plan.md --dry-run                                # print the brief, send nothing
ingot handoff status <run> --json
ingot handoff checkout <run>                                               # fetch and check out the run's branch

Every option is on Agent hand-off.

App Preview

preview lists what the App Preview tab sees: local dev servers first with their framework and page title, then other local web pages (never Ingot's own ports or desktop apps), and the device sizes. check tells whether a port or URL answers and exits 1 when it does not, so scripts can wait for a dev server:

ingot preview servers --dev                       # dev servers only; --exclude <port>, --json
ingot preview devices                             # sizes and the ids --device takes
ingot preview check 5173 --wait 30                # wait up to 30 s for the dev server to answer
ingot preview check localhost:3000/cart --device iphone-15-pro --json

Every option is on App Preview.

Mobile preview

preview mobile lists what the Devices panel of Mobile preview sees: booted iOS Simulators, paired iPhones and iPads (xcrun devicectl), Android emulators and phones (adb), a running Metro or Expo server, and what is missing with how to install it. open sends a port or URL to a device by id or name, with the address that device can reach: localhost on simulators, 10.0.2.2 on the Android emulator and the LAN address on phones. --app opens the React Native or Expo app instead. preview qr prints a QR code of the LAN address in the terminal:

ingot preview mobile --json                       # devices by group, Metro, and missing tools
ingot preview mobile open "iPhone 15 Pro" 5173    # a device by id or name, a port or URL; --lan <ip>
ingot preview mobile open emulator-5554 --app     # Expo Go, a development build or the installed app
ingot preview mobile connect 192.168.1.40:5555    # adb connect for Android over Wi-Fi
ingot preview qr 5173 --invert                    # QR code of the LAN address; --expo for Expo Go, --metro <port>

Every option is on Mobile preview.

Agents

agents prints every agent by status, like the Agent Command Center in Ingot: the chats of every open Ingot window on this machine and, with a personal access token (ingot_pat_…) in --token or INGOT_TOKEN, your cloud agent runs:

ingot agents                       # every agent by column
ingot agents --status needs-you    # approvals, questions and paused runs
ingot agents --local --json
ingot agents cancel <cloud-run-id>

Every option is on Agent Command Center.

Usage and on-demand

usage shows your Ingot account's token units, usage per model tier, Zaprex minutes and on-demand state, and changes on-demand and team member caps. It needs a personal access token (ingot_pat_...) in --token or INGOT_TOKEN; the server is --server, then INGOT_SERVER, then https://www.ingotide.com.

npx @ingotide/cli usage                           # units left, per tier, Zaprex, on-demand
npx @ingotide/cli usage on-demand on --cap 25     # on-demand with a $25 monthly cap; off turns it off
npx @ingotide/cli usage cap dev@example.com none  # remove a team member's unit cap

Every option is on Usage & on-demand.

Automations

automations works with the automations in .ingot/automations/. list, validate, new and test run offline; sync, run and fires use your Ingot account with the same token and server as usage. The repository is --repo, else this folder's origin remote.

npx @ingotide/cli automations validate                                   # exits 1 when a file has errors
npx @ingotide/cli automations new "Fix CI" --on ci_failure --prompt "Fix the build" --goal "CI passes" --check "npm test"
npx @ingotide/cli automations test --webhook '{"title":"Deploy failed"}'  # which automations start, and why not
npx @ingotide/cli automations sync --secrets                             # upload run: cloud files; print the hook secrets

External agents (ACP)

acp runs the same external agents as the IDE's External Agents panel, from built-in, ~/.ingot/acp.json and the project's .ingot/acp.json. The agent reads and writes files inside --cwd only; built-in agents use the provider set up in the agent itself, and an agent you add can take its API key from its keyEnv variable.

npx @ingotide/cli acp agents                                  # built-in and custom agents, and how each starts
npx @ingotide/cli acp doctor goose --session                  # protocol version, sign-in methods, can it open a session
npx @ingotide/cli acp run opencode --prompt "Explain src/cart.ts" --deny # reply on stdout; plan and tools on stderr
npx @ingotide/cli acp run team-bot --file task.md --allow --json  # one JSON event per line
npx @ingotide/cli acp add team-bot --command team-bot --args="--acp" --key-env TEAM_BOT_API_KEY [--global]

Without --allow, --deny or --read-only, run asks in a terminal and refuses in CI and pipes. --timeout <s> limits setup (default 120 s). Exit codes: 0 done, 1 failed, 2 usage, 3 refused, 4 stopped.

Arena

arena runs Arena mode battles in the terminal. run sends one task to two models picked at random from --models (three cheap models by default) and shows the answers as Agent A and Agent B without naming the models. It needs OPENROUTER_API_KEY and stops before calling when the worst-case cost is over --max-cost (default $0.02, exit 3). vote <id> <a|b|tie|bad> saves the vote and reveals the models; leaderboard and votes read the same .ingot/arena/votes.jsonl the IDE writes. --mock (or INGOT_ARENA_MOCK=1) gives canned answers with no network, for CI.

npx @ingotide/cli arena run "Write a debounce helper in TypeScript"   # two hidden models answer
npx @ingotide/cli arena run "Explain this function" --with src/cart.ts --vote a
npx @ingotide/cli arena vote arena-mhj3k2ab-0a1b a                      # a, b, tie or bad
npx @ingotide/cli arena leaderboard                                     # Elo table from .ingot/arena/votes.jsonl
npx @ingotide/cli arena run "Say hi" --mock                             # canned answers, no key or network (CI)

Extensions

extensions manages Ingot store extensions from the terminal. Every one is free today (price 0, tier free) and goes through the same access check as a paid one would. install and uninstall take the listing id, the extension id or the store's ingot://install/extension/<id> link, and edit the Ingot settings.json (--dir, else THEIA_CONFIG_DIR, else ~/.ingot), so open windows pick the change up. Uninstalling the Agent Command Center turns it off, resets its settings and deletes the board files in agent-board/. suggestions on|off sets Suggest features in chat; suggestions reset <id> brings back a suggestion you closed with ×.

npx @ingotide/cli extensions list                          # id, price, tier, installed (--json for scripts)
npx @ingotide/cli extensions info agent-command-center
npx @ingotide/cli extensions install agent-command-center
npx @ingotide/cli extensions uninstall agent-command-center
npx @ingotide/cli extensions suggestions off               # on | off | reset <id>

Session Panes

panes edits .ingot/panes.json, the sessions Session Panes opens side by side when you click Start in Ingot. It never calls a model and never starts an agent. add takes an optional prompt and --title, --model, --mode agent|ask|plan|debug, --tab chat|files|changes|terminal, --worktree and --id, and refuses a ninth pane. remove takes a pane's number or id. validate exits 1 when the file has errors (bad JSON, more than 8 panes, bad or duplicate ids, unknown modes or tabs); unknown keys and missing ids are only warnings. An edit never rewrites a file with errors.

npx @ingotide/cli panes                                    # the panes with a layout drawing; --json
npx @ingotide/cli panes add "Write tests for the cart" --tab changes --worktree
npx @ingotide/cli panes layout rows                        # grid, columns or rows
npx @ingotide/cli panes validate                           # in CI
npx @ingotide/cli panes grid 5 --layout columns            # how 5 panes are laid out, no file needed

Agent layout

layout reads and writes the seven ingot.agentLayout.* settings of the focused agent layout in the normal settings files, the later winning: ~/.ingot/ingot.settings.json (--global), ~/.ingot/settings.json (--user) and the project's .ingot/settings.json (--project, the default for set and reset). Settings take the short name (review) or the full key (ingot.agentLayout.review); switches take true/false or on/off. set and reset keep the file's comments and formatting, and never rewrite a file that isn't valid JSON (exit 1). Ingot applies changes live. It never calls a model.

npx @ingotide/cli layout                         # each setting, its value and its source file; --json
npx @ingotide/cli layout set review editor       # Review opens the Agent Review editor in this project
npx @ingotide/cli layout set enabled off --user  # the classic chat panel for you
npx @ingotide/cli layout reset review            # back to the user, global or default value
npx @ingotide/cli layout list --json             # every setting with its values, default and description

Agent Sandbox

sandbox shows the OS sandbox Agent Sandbox gives agent commands on this machine and edits the project allow-list in .ingot/policy.json. It never calls a model and never runs an agent. status (the default) says whether the sandbox works here and, on Linux without bubblewrap, the command that installs it; --platform darwin|linux|win32 shows what another system would use. allow and remove take command, host or path and a value: commands go to commands.allow, hosts to network.allow and folders to sandbox.allowWrite. They refuse to rewrite a file with comments or a JSON error (the Agent Sandbox panel keeps comments). wrap prints the command line Ingot runs, with --network allow|deny.

npx @ingotide/cli sandbox                                  # this machine's sandbox and the project's settings; --json
npx @ingotide/cli sandbox status --platform linux          # what Ingot would use on Linux (darwin, linux, win32)
npx @ingotide/cli sandbox list                             # the allow-list; --json
npx @ingotide/cli sandbox allow command "npm run lint"     # also: host <host>, path <folder>
npx @ingotide/cli sandbox remove host registry.npmjs.org
npx @ingotide/cli sandbox wrap "npm test" --platform linux --network deny

Git hosts

git connects the hosts Git Hosts supports and works with them from a terminal or a script. connect takes gitlab, bitbucket-cloud, bitbucket-dc, azure-devops, gitea, forgejo, generic or a URL (detected), with --url for self-hosted servers, then --token (else INGOT_GIT_TOKEN, else it asks) or --oauth --client-id <id>. Bitbucket Cloud API tokens also need --user <Atlassian e-mail>. The repository commands use the current folder's origin when it is on a connected host, else --repo owner/name and --account. Accounts are shared with the Ingot app in ~/.ingot/git-hosts.json; the CLI keeps its tokens in ~/.ingot/cli/git-hosts-credentials.json (mode 600). Tokens are never printed, also not in errors.

npx @ingotide/cli git hosts                                   # supported hosts, token pages and scopes
npx @ingotide/cli git connect gitlab --token "$GITLAB_TOKEN"  # or set INGOT_GIT_TOKEN
npx @ingotide/cli git connect https://git.example.com         # detects the host, then asks for a token
npx @ingotide/cli git connect gitlab --oauth --client-id <id> # OAuth with PKCE in your browser
npx @ingotide/cli git prs --state open                        # this clone's origin; --repo and --account otherwise
npx @ingotide/cli git pr create --title "Fix VAT" --source vat --draft
npx @ingotide/cli git ci --ref main                           # recent CI runs
npx @ingotide/cli git mcp --read-only                         # the git-hosts MCP server on stdio

git mcp serves the git-hosts tools (accounts, repos, branches, pull requests, issues, CI, and creating pull requests and issues unless --read-only) to any MCP client over stdio: { "git-hosts": { "command": "ingot", "args": ["git", "mcp"] } }.

MCP servers

mcp works with the MCP servers in ~/.ingot/mcp.json and the project's .ingot/mcp.json, the files Ingot reads (a project server wins over a global one with the same name). Remote servers use Streamable HTTP (MCP 2025-11-25) and sign in with login: Ingot's OAuth flow with discovery, dynamic client registration (or --client-id, --client-secret, --scopes, else the server's auth in mcp.json), PKCE and a loopback redirect on 127.0.0.1. Local servers run over stdio. check connects, lists tools and pings (--count, up to 20) and prints Healthy, Slow, Degraded, Down or Sign-in required; it exits 1 when a server is down, degraded or needs sign-in, so it fits in CI. call runs one tool with --args (a JSON object); tools the server marks destructive need --yes. Values written as ${keychain} in mcp.json come from the environment variable of the same name, a keychain CLIENT_SECRET from INGOT_MCP_CLIENT_SECRET. Tokens are kept in ~/.ingot/cli/mcp-credentials.json (mode 600), apart from Ingot's own, and are never printed. See Remote MCP, OAuth & health.

npx @ingotide/cli mcp list                                    # servers, transport, signed in or not; --json
npx @ingotide/cli mcp login linear                            # OAuth with PKCE in your browser
npx @ingotide/cli mcp check --count 3                         # health of every server; exit 1 if one is down
npx @ingotide/cli mcp tools linear                            # tools with read-only / write / destructive
npx @ingotide/cli mcp call linear list_issues --args '{"state":"open"}'
npx @ingotide/cli mcp call tracker delete_issue --args '{"id":"ENG-2"}' --yes
npx @ingotide/cli mcp logout linear

extensions (short ext) runs Marketplace search in the terminal. search asks the Ingot Store and Open VSX in parallel and prints one list, deduplicated by id, with the sources that have each result; a source that fails is reported and the others still show. --source ingot,open-vsx picks sources, --limit (up to 50) and --json are optional. The Microsoft Marketplace is asked only with --microsoft-marketplace, because Microsoft's terms allow its extensions only in Microsoft products; the CLI prints that note when you use it. install takes an id (downloads the .vsix from the first source that has one, --source to choose) or a local .vsix, checks that its extension/package.json matches, and copies it into Ingot's extensions folder (--dir, else INGOT_EXTENSIONS_DIR, else $THEIA_CONFIG_DIR/extensions, else ~/.ingot/extensions); Ingot installs it on its next start. An existing file is kept unless --force. inspect prints a .vsix's id, version and engine range without installing it. Exit codes: 0, 1 when nothing was found or a check failed, 2 for usage errors.

The Chrome guard applies here too: extensions that would replace Ingot's window chrome are marked blocked: in search and never saved by install (exit code 1); one that only changes chrome defaults is saved with a warning, and inspect prints Shell guard: ok, blocked or warning. inspect also runs the extension guard Ingot runs before it starts an extension, with its built-in lists: Extension guard: ok, or not started in Ingot with the reason and the Ingot alternative, so an extension author (a COBOL language pack, say) can check a .vsix before publishing it.

npx @ingotide/cli extensions search prettier                       # Ingot Store + Open VSX, one list
npx @ingotide/cli extensions search prettier --microsoft-marketplace --json
npx @ingotide/cli extensions install rust-lang.rust-analyzer        # the .vsix into Ingot's extensions folder
npx @ingotide/cli extensions install ./my-tool-1.0.0.vsix --force  # a local file, replacing an older copy
npx @ingotide/cli extensions inspect ./my-tool-1.0.0.vsix          # id, version and engine, nothing installed
npx @ingotide/cli extensions sources                               # each source, its URL and whether it is on

Habits

habits works on Habits, the typed knowledge folder .ingot/habits/: one Markdown file per type of fix with lasting knowledge, one bullet per entry. init creates the default type files that are missing and never overwrites. add classifies the knowledge like the IDE (a type's name 2 points, each keyword 1, general when nothing fits) or takes --type, creates the file when it is missing and skips an entry that is already there. relevant prints which type files the agent reads for a task and the exact text it gets. new <type> <name> writes the same files Ingot writes: new type i18n is a new type file (like new-type), new playbook <name> a playbook (--when and --step); a bare new <name> is a playbook, as before. Scenario playbooks (when/steps files) keep their show, new, validate, match, prompt and remove actions. It never calls a model.

npx @ingotide/cli habits init                                          # bug.md, defect.md, … general.md
npx @ingotide/cli habits add "Always add a regression test before fixing a crash"   # → bug.md
npx @ingotide/cli habits classify "Never log access tokens"            # → security.md, and why
npx @ingotide/cli habits relevant "the checkout crashes on an empty cart"
npx @ingotide/cli habits new-type i18n --keyword locale                # your own type file
npx @ingotide/cli habits new type i18n --keyword locale                # the same, as new <type> <name>
npx @ingotide/cli habits new playbook Release --when "Shipping a version" --step "Tag it"
npx @ingotide/cli habits show Release                                   # a playbook's trigger and steps
npx @ingotide/cli habits types --json

Tokens and registry

The token is taken from, in order: --token, the INGOT_PUBLISH_TOKEN environment variable, then the token saved by ingot login for that registry.

The registry is --registry, then INGOT_REGISTRY, then https://www.ingotide.com. Registries must use https://; plain http:// is allowed for localhost only (for testing against a local portal).

VariableUsed for
INGOT_PUBLISH_TOKENthe publish token (CI)
INGOT_REGISTRYanother store, for example http://localhost:3000
INGOT_CLI_HOMEwhere login saves credentials (default ~/.ingot/cli)

Exit codes and errors

CodeMeaning
0success
1the command failed (validation errors, the store refused the upload, network error), or merge left conflict markers
2wrong usage (unknown command or option, missing argument)
3rules test skipped a test, or review, tab predict or image notes did not call the model, because of the cost cap; or the cloud agent run that handoff --watch followed did not succeed

When the store refuses a request, the CLI prints the error code and what to do:

ErrorWhat to do
invalid_tokenthe token is unknown or revoked: create a new one, ingot login again
token_expiredcreate a new token
publisher_mismatchpublisher in ingot.json must be your handle
version_exists, version_not_neweringot version patch, then publish
invalid_manifest, invalid_contentsfix the listed fields or files (ingot validate shows the same list)
package_too_largeremove files you don't need from files
rate_limitedmore than 30 uploads in an hour: wait and retry
publishing_unavailablethe store can't take uploads right now