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>.

Beta. Store publishing is new. The steps below work today against www.ingotide.com; commands and limits may still change. During the Beta the @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).

  1. Sign in to your Ingot account.
  2. Open Dashboard › Publisher (/dashboard/publisher).
  3. Pick a handle (3 to 32 lowercase letters, digits and dashes), a display name and, optionally, a website.
  4. 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--typeStarter filesEnds up in Ingot as
Color themethemethemes/<name>.jsona theme under Settings › Appearance
Rules packrulesrules/<name>.mdcfiles in the project's .ingot/rules/
Habits packhabitshabits/<id>.jsonpatterns Habits watches for
MCP servermcpserver/index.mjs (a working stdio server)an entry in .ingot/mcp.json
Rex templaterex-templatetemplates/<name>.mda 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 .mdc files 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.

  1. Open Dashboard › Publisher.
  2. Under Publish tokens, enter a name (for example Laptop or GitHub Actions) and pick when it expires: 30, 90, 180 or 365 days.
  3. 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.

Opening community extensions straight from the store (the 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.