Creator guide
Build a color theme, rules pack, Habits pack, MCP server or Rex template and publish it to the Ingot store with the ingot command-line tool, from an empty folder to a listing at /marketplace/<publisher>.<name>.
@ingotide/cli package may not be on npm yet: if npm install can't find it, build it from source (step 1).What you'll do: install the CLI, create your publisher profile, scaffold an extension, test it in a real project, package it as a .ingotx file, create a publish token, and publish. Updating and unpublishing are at the end. Plan on 15 minutes for your first extension.
1. Install the CLI
You need Node.js 22 or newer.
npm install -g @ingotide/cli
ingot --version
You can also run any command without installing: npx @ingotide/cli <command>.
If the package isn't on npm yet, build it from the Ingot portal repository:
git clone https://github.com/yaghobieh/ingot-portal.git
cd ingot-portal/packages/ingot-cli
npm ci && npm run build && npm link
ingot --version
ingot help lists every command, and ingot <command> --help shows its options. The full list is in the CLI reference.
2. Create your publisher profile
Everything you publish belongs to a publisher. Its handle is the publisher field of every ingot.json and the first half of every extension id (acme.react-rules).
- Sign in to your Ingot account.
- Open Dashboard › Publisher (/dashboard/publisher).
- Pick a handle (3 to 32 lowercase letters, digits and dashes), a display name and, optionally, a website.
- Click Create publisher.
The handle can't be changed later. Handles that look official (ingot, zaprex, ingot-…, official, support and similar) are reserved.
3. Scaffold an extension
ingot init creates a folder with a valid ingot.json, a README, a CHANGELOG, an MIT LICENSE, a .gitignore, starter files for the type you pick, and a GitHub Actions workflow that publishes when you push a version tag.
ingot init my-theme --type theme --publisher acme
cd my-theme
Run it without options and it asks for the type, name, publisher and description. Pick the type that matches what you're building:
| Type | --type | Starter files | Ends up in Ingot as |
|---|---|---|---|
| Color theme | theme | themes/<name>.json | a theme under Settings › Appearance |
| Rules pack | rules | rules/<name>.mdc | files in the project's .ingot/rules/ |
| Habits pack | habits | habits/<id>.json | patterns Habits watches for |
| MCP server | mcp | server/index.mjs (a working stdio server) | an entry in .ingot/mcp.json |
| Rex template | rex-template | templates/<name>.md | a template Rex runs in Zaprex |
One command per type:
ingot init my-theme --type theme --publisher acme --yes
ingot init react-rules --type rules --publisher acme --yes
ingot init team-habits --type habits --publisher acme --yes
ingot init word-tools --type mcp --publisher acme --yes
ingot init nightly-fix --type rex-template --publisher acme --yes
--yes accepts the defaults. Add --ci gitlab for a GitLab pipeline instead of GitHub Actions, or --ci none for no CI file. Extension types explains every type and its files.
4. Add rules, habits, commands and MCP servers
A package can carry more than its main type: a rules pack can add slash commands, a theme can ship a rules file, and so on. ingot add writes the file and its ingot.json entry in one go:
ingot add rule testing --description "How we write tests"
ingot add habit no-any --match ":\s*any\b" --rule "- Don't use the any type."
ingot add command review --description "Review the open files"
ingot add mcp acme-api --command npx --env ACME_API_KEY="Your Acme API key" -- -y @acme/mcp-server
ingot add mcp docs --url https://mcp.acme.dev/sse
- Rules are Markdown or
.mdcfiles with optional frontmatter (description,globs,alwaysApply), the same as Rules. - Commands become
/<name>in agent chat. - MCP servers run a local command or connect to a remote
https://URL. List environment variables with a description of what to enter; never put a secret in the package.
Edit the files, then check your work at any time:
ingot validate
validate runs exactly the checks the store runs on upload, so a package that validates locally won't be rejected for its contents.
5. Test it in a real project
ingot try installs the extension into a project the way the store will:
ingot try ~/code/my-app
- The whole package is copied to
~/code/my-app/.ingot/extensions/acme.my-theme/. - Rules go to
.ingot/rules/, commands to.ingot/commands/, and MCP servers are merged into.ingot/mcp.json(with${extensionDir}replaced by the real folder).
Open the project in Ingot and use the extension: switch to the theme, ask the agent something your rules cover, run /review, or call your MCP server's tools. Run ingot try again after every change. To undo, delete the copied files.
6. Package it
ingot package
This validates again and writes acme.my-theme-0.1.0.ingotx: a ZIP file with ingot.json, your README, CHANGELOG and LICENSE, and every file the manifest points at. Only those files go in, plus anything you list under files in ingot.json. Packages are deterministic (the same sources give the same bytes) and the CLI prints the SHA-256.
Limits: 4 MB per package, 20 MB unpacked, 2 MB per file, 200 files. See Manifest for the details.
7. Create a publish token
The CLI publishes with a publish token, not your password.
- Open Dashboard › Publisher.
- Under Publish tokens, enter a name (for example
LaptoporGitHub Actions) and pick when it expires: 30, 90, 180 or 365 days. - Click Create token and copy it. It starts with
ingot_pub_and is shown only once.
Tokens can only publish and unpublish as your publisher; they can't read or change anything else in your account. Ingot stores only a hash of each token. Revoke a token from the same page and it stops working at once. Use one token per machine or CI system so you can revoke them separately.
8. Sign in and publish
ingot login
Paste the token when asked (the input is hidden). The CLI checks it with the store and saves it in ~/.ingot/cli/credentials.json, readable by you only. ingot whoami shows which publisher it belongs to.
Then publish from the extension folder:
ingot publish
publish packages the folder and uploads it. To upload a file you already built, pass it: ingot publish acme.my-theme-0.1.0.ingotx. The store validates the package again, stores the version, and prints its page:
Publishing acme.my-theme@0.1.0 to https://www.ingotide.com…
Published acme.my-theme@0.1.0.
Store page: https://www.ingotide.com/marketplace/acme.my-theme
Your extension now shows in the store under From the community, in its category and in search, with a Community badge. Its page has the README, the version history and a Download .ingotx button.
ingot:// install link) needs a newer Ingot build. Until then, the item page shows how to install by hand: download the .ingotx, unzip it, and run ingot try <project> --cwd <folder>.9. Publish updates
Every upload needs a new, higher version. Bump it with ingot version, which also adds a heading to CHANGELOG.md:
ingot version patch # 0.1.0 → 0.1.1 (or minor, major, or an exact 1.2.0)
ingot publish
Versions follow semantic versioning: 1.2.3, or a pre-release like 1.3.0-beta.1. The store refuses a version that was already uploaded or that isn't higher than the latest one, so a number is never reused, even after an unpublish.
To publish from CI instead, commit, tag and push; the workflow from ingot init does the rest:
git commit -am "v0.1.1" && git tag v0.1.1 && git push --follow-tags
Setting that up takes five minutes: see Publish from CI/CD.
10. Unpublish
ingot unpublish acme.my-theme@0.1.1 # one version
ingot unpublish acme.my-theme # every version
Run it inside the extension folder without an id to use ingot.json. The CLI asks you to type the extension name to confirm; pass --yes in scripts. You can also click Unpublish next to the extension in Dashboard › Publisher.
Unpublishing takes the version (or the whole extension) out of the store, the sitemap and search. Copies people already installed keep working. The version number stays used: publish the next version to come back.
Before you publish for real, read the store guidelines. Look up any field in Manifest, and every flag in the CLI reference.