@orbito/omm (1.3.0)
Installation
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/npm install @orbito/omm@1.3.0"@orbito/omm": "1.3.0"About this package
OMM — OrbitoModulesManager
CLI for Orbito modules:
- registry (
modules.orbito.pl) — pack and publish modules, thenpm publishof Orbito modules; - Orbito Core (
v2.orbito.pl) — install a module version in your test company, read its logs and problems, call its methods and update it — the build/test loop without the web panel.
The package identity (module code and version) comes only from module.json
in the module directory. The module card in the registry is created by omm init
(or in the developer panel) — omm publish never creates it.
Installation
npm config set @orbito:registry https://git.kozminski.net.pl/api/packages/orbito/npm/ # once per machine
npm i -g @orbito/omm
@orbito/omm and @orbito/api-lib are not on npmjs.org: they live in the Orbito npm
registry, which allows anonymous downloads (no token) but needs the @orbito scope mapped
in ~/.npmrc:
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/
Without this line npm i -g @orbito/omm and npm install in a module fail with 404.
Requires Node.js >= 18.13. To work on the CLI itself: npm install && npm link
in the repo directory.
Publishing a new CLI version: bump version in package.json and run npm publish
(the registry is set in publishConfig).
Usage
New module (omm init)
omm init "Hello" # create the module card in the registry + scaffold ./hello
omm init "Hello" --description "Greets people" --dir my-hello
omm init "Hello" --code acme/hello # the card already exists: scaffold only, no registry call
omm init <name> [--dir <dir>] [--code <org/name>] [--description <text>] [-r, --registry <url>]
<name>is the display name of the module card.- Without
--codethe command creates the module card in the registry (POST /developer/modules, needsomm login); the registry assigns the module code<username>/<slug of the name>. With--codethe card must already exist and the registry is not called. --dirdefaults to the name part of the code (acme/hello→hello). The directory must not exist or must be empty.- The module is created from the template built into
omm(the same code as thehello-moduleexample in the docs):module.json,package.json,index.js,pages/hello.yamland.gitignore, with the module code put into every file and--descriptionintopackage.json.npm installis not run. --jsonprints{ code, dir, files, cardCreated }.
Next: cd <dir> && npm install, then follow the build loop:
https://orbito.pl/docs/agents/build-loop.html
Registry
omm login # password login; creates and saves a publish token
omm login --token omm_abc... # CI: use an existing publish token
omm whoami # who is logged in
omm logout # revoke the token and remove it from the config
omm pack --dry-run # show what goes into the package
omm pack # build the ZIP locally (no upload)
omm publish # pack + upload a DRAFT + wait for the Docker build
omm publish --release # as above + publish in the registry (draft → published)
omm publish --no-wait # upload a draft and do not wait for the build
omm publish --changelog "..." # with release notes
omm secrets list # module secrets with their status (never values)
omm secrets set ALLEGRO_CLIENT_ID # set a value (hidden prompt)
omm secrets unset ALLEGRO_CLIENT_ID # remove a value
By default publish uploads a draft — for testing. Publishing in the registry
(visible to all companies) requires an explicit --release.
The version of a new publish is bumped by editing version in module.json
(it must be a semver higher than the last published version). A draft of the
same version can be uploaded again — it overwrites the previous draft.
Orbito Core (test loop)
omm login --core # e-mail + password of your Orbito account (JWT, 48 h)
omm login --core http://localhost:3003 # another core
omm login --core --token <jwt> # CI: use an existing core JWT
omm whoami --core # account and working company
omm logout --core # remove the core session from the config
omm company list # your companies (* = working company)
omm company use <id> # set the working company (id or list number)
omm company use # choose interactively
omm company dev-token # required once per company before installing your drafts
omm install # install the version from module.json (+ dependencies)
omm install --name "Shop B" # a second instance of a non-singleton module
omm instances # instances of the module in the company
omm logs # module logs of today
omm logs --since 2026-10-13T10:00:00Z
omm logs --day 2026-10-12
omm logs --container # Docker stdout/stderr of the module container
omm problems --status waiting # problems reported by the module
omm call getOrders --params '{"limit": 5}' # call a module method, print its result
omm update # update the instance to the version from module.json
# (same version: reload the container with a fresh image)
A typical loop: omm publish (draft) → omm company dev-token (once per company) →
omm install → omm logs / omm problems / omm call → fix → omm publish (overwrites
the draft) → omm update (reload) → … → omm publish --release. The version does not have
to be bumped while you iterate on a draft.
- The module code (and, for
install/update, the version) is read frommodule.jsonin the current directory (-C <dir>for another one).instances,logs,problemsandcallalso accept--module <org/name>. update,logsandcallact on the only active instance of the module in the working company. With more instances the command fails and lists their ids — choose one with--instance <id>.installalways installs missing dependencies too (withDependencies).updatecompares the instance version withmodule.json. A different version updates the instance (POST /m/i/:id/update); the same version reloads it instead (POST /m/i/:id/reload): the container is stopped and its next start pulls the image again, so an overwritten draft takes effect.--jsonprints the core response plus"action": "update"or"action": "reload".callruns the method with the permissions of the logged-in user; the core wraps the result in a one-element array —ommprints the element itself.company dev-tokensets the company dev-token to your developer token from the registry. It is required before the firstinstallof a draft: the registry hands out draft images only to companies holding the author's token, so without itinstallandupdateof a draft fail with 404 (ommthen suggestsomm company dev-token, in--jsonashint). It also makes the company marketplace show your draft versions. Published versions do not need it. The token is saved by passwordomm login(the registry only hands it out for a password session); afteromm login --tokenpass it explicitly:omm company dev-token <uuid>(developer panel).- The core JWT is valid for 48 h and is refreshed automatically before a core command when
less than 24 h are left. An expired session ends with an error asking for
omm login --core. - Every core command accepts
--core <url>and (exceptcompany list/use)--company <id>.
Company automations (omm automation)
Automations of the working company: browse them, write their graph as a JSON file, enable them and diagnose their runs — without the editor in the web panel.
omm automation list --enabled --query invoice # ID, ENABLED, NAME, TRIGGERS, ACTIONS, BLOCKING
omm automation get <id> # graph (in the file format below) + blocking elements
omm automation elements --kind action --query label # triggers and actions available in the company
omm automation element set_var # full definition as JSON: params, outputs, emits/requires
omm automation create -f graph.json # create a DISABLED automation (validated by the core)
cat graph.json | omm automation create -f - # the graph from stdin
omm automation update <id> -f patch.json # replace the given graph fields
omm automation enable <id> # enable it (separate step, see below)
omm automation disable <id>
omm automation duplicate <id> # disabled copy
omm automation delete <id> --yes # also removes its runs and problems
omm automation runs --automation <id> --status errored --event 12345
omm automation run <runId> # run header, event params and steps
omm automation var list
omm automation var get <key>
omm automation var set <key> <value> # values are text
The graph file (create needs all of it, update any subset of the fields):
{
"name": "Label for new orders",
"desc": "Optional description",
"triggers": [{ "type": "<trigger type>", "params": {} }],
"actions": {
"a1": {
"type": "<moduleCode>:<action code>",
"params": { "__instanceId": "<instance id>" },
"branches": { "next": null }
}
},
"startActionId": "a1"
}
typeis the element type fromomm automation elements; module elements are<moduleCode>:<code>and needparams.__instanceId(the instance that runs them).branchesmaps the action outputs (next, or e.g.true/falseof a condition) to the next action id ornull.- Draft → enable.
createalways saves a disabled automation andupdatenever changesisEnabled; a graph file withisEnabledis rejected. Enable it explicitly withomm automation enable <id>— the core then checks that every element is available and the action params are valid. - The output of
omm automation get <id> --jsoncan be edited and fed back toomm automation update <id> -fonceisEnabledis removed — read-only fields (_id,validation,generatedName, …) are dropped before sending. createandupdatesend?strict=true: the core validates the whole graph (elements, params, branches, template variables) and rejects an invalid one with HTTP 422. The errors are printed one per line aspath: message (CODE); for a rejectedenablethe blocking elements (triggers.0: <type> (<status>)) and invalid action params. With--jsonthey are in thevalidationfield of the error on stderr:
{"error":"Automation graph is invalid","status":422,"validation":{"errors":[{"path":"actions.a1.params.__instanceId","code":"REQUIRED","message":"..."}]}}
--jsonprints{ automationId, name, isEnabled }forcreate,update,enable,disableandduplicate, the core response for the other commands, and a list of elements withkind(trigger/action) forelements.elementprints JSON also without--json.listshows up to 50 automations,runsup to 20 runs (--limit, the core caps runs at 50).- Validation messages come from the core as they are (currently in Polish).
Installing the agent skill (omm skill install)
The orbito-modules skill (SKILL.md) teaches AI coding agents — Claude Code, Codex and
OpenCode — how to build, test and publish Orbito modules. omm skill install downloads the
current skill and copies it into the agents' skill directories; run it again to update it.
It works the same on Windows, macOS and Linux.
omm skill install # agents whose directory exists in your home directory
omm skill install --project # .claude/.codex/.opencode of the current directory
omm skill install --agent codex --agent opencode
omm skill install --all --no-npm
omm skill install [--project] [--all] [--agent <name>...] [--no-npm]
- By default the skill goes to every agent whose directory exists (
~/.claude,~/.codex,~/.config/opencode; with--project:.claude,.codex,.opencodein the current directory); if none exists, to Claude Code. The file lands in<agent dir>/skills/orbito-modules/SKILL.md. --allinstalls for all three agents;--agent claude|codex|opencode(repeatable) only for the given ones.- The skill is downloaded from
https://orbito.pl/docs/skill/SKILL.md(OMM_SKILL_URLoverrides it, also with afile://URL) and must declarename: orbito-modules, otherwise nothing is written. - Unless
--no-npmis given, the command maps the@orbitoscope in~/.npmrc(npm config set @orbito:registry …). When npm is missing or fails, it prints the line to add by hand; the skill is installed anyway (exit code 0). --jsonprints{ installed: [{ agent, file }], npm: "configured"|"skipped"|"failed", skillUrl }.- No update notices are printed after this command (the fresh copies would be reported as outdated by the check started before it).
https://orbito.pl/docs/skill/install.sh (curl … | sh) installs omm and runs
omm skill install with the same options.
Output for scripts and AI agents (--json)
--json (anywhere on the command line) prints only the result as JSON on stdout; progress
messages are suppressed. Errors go to stderr as {"error": "...", "status": 404} (status
is the HTTP status or null, plus code/details/validation when the server sends them and
hint when omm knows the next step) and the exit
code is 1. Commands never read stdin except the interactive ones: login without --token,
company use without an argument and secrets set without OMM_SECRET_VALUE — and
automation create/update -f -, which read the graph from stdin.
omm instances --json
omm call ping --json
Update notices and omm doctor
Once a day omm checks the latest @orbito/omm and @orbito/api-lib in the Orbito npm
registry and the current agent skill (https://orbito.pl/docs/skill/version.json). The check
starts together with the command and its result is printed after it (also after an error),
always on stderr — stdout stays the clean command result:
! omm 1.1.0 is available (you have 1.0.1) — npm i -g @orbito/omm (https://orbito.pl/docs/agents/changelog.html)
With --json it is one line on stderr:
{"notices":[{"kind":"omm|sdk|skill","message":"...","fix":"...","url":"..."}]}. Notices:
omm— a neweromm; fixnpm i -g @orbito/omm, link to the changelog;sdk— only in a module directory (module.json): the lowest version of the@orbito/api-librange inpackage.json(^x.y.z,~x.y.z,x.y.z,>=x.y.z) is older than the latest; fixnpm i @orbito/api-lib@latest;skill— a localorbito-modules/SKILL.mdof Claude Code, Codex or OpenCode (user:~/.claude/skills,~/.codex/skills,~/.config/opencode/skills; project:.claude/skills,.codex/skills,.opencode/skillsin the current directory) differs from the published one; fix:omm skill install(omm skill install --projectfor project copies).
The result is cached for 24 h in the config (updateCheck); each request has a 3 s timeout and
network errors are silent (the previous result stays). OMM_NO_UPDATE_CHECK=1 turns the
automatic check off (CI).
omm doctor checks the whole setup at once and always fetches fresh versions
(also with OMM_NO_UPDATE_CHECK). Checks (ok / warn / fail, with a fix command):
node (engines), omm (vs latest), npm-scope (npm config get @orbito:registry),
registry-login (token + whoami, saved developer token), core-login, company,
module (manifest, package.json with @orbito/api-lib, SDK vs latest) and skill:<agent>
per agent with the skill installed. The exit code is 1 only when a check fails.
omm doctor # table + fix lines
omm doctor --json # { "checks": [{ "name", "status", "message", "fix"? }], "notices": [...] }
Configuration
~/.config/omm/config.json— publish token per registry (registries) and session per core (cores[url] = { token, expiresAt, email, companyId },core= last used core), last update check (updateCheck, cached 24 h).OMM_TOKEN— publish token from env (overrides the config; for CI).OMM_REGISTRY/--registry— registry API URL (defaulthttps://modules.orbito.pl/api).OMM_CORE/--core <url>— core API URL (default: last used, thenhttps://v2.orbito.pl/api).OMM_CORE_TOKEN— core JWT from env (overrides the config, not refreshed).OMM_COMPANY/--company <id>— working company (overridesomm company use).OMM_SECRET_VALUE— value foromm secrets setwithout a prompt (CI).OMM_NO_UPDATE_CHECK=1— no automatic update check (CI);omm doctorstill checks.OMM_PACKAGES_REGISTRY— npm registry of the@orbitopackages (defaulthttps://git.kozminski.net.pl/api/packages/orbito/npm/): source of the latest versions, the valueomm doctorexpects in@orbito:registryand the oneomm skill installsets there.OMM_SKILL_URL— source ofSKILL.mdforomm skill install(defaulthttps://orbito.pl/docs/skill/SKILL.md;file://URLs work too).
What goes into the package
If module.json has a files field (array of paths) — only the listed files and
directories (module.json is always included). Without files — the whole module
directory except: node_modules/, .git/, .env*, .npmrc, *.zip,
make-zip.sh, editor files.
.npmrc is excluded by default (secrets in the package). If the module's Docker
build needs private npm packages, add --include-npmrc deliberately.
Module secrets (omm secrets)
App keys (e.g. a marketplace client ID/secret) should not live in the module code. The registry stores the values — encrypted, globally per module code (not per version or company). The core fetches them when a module container starts and passes them as environment variables.
The module declares its secrets in module.json (without values):
{
"name": "core/allegro",
"version": "1.2.0",
"secrets": [
{ "name": "ALLEGRO_CLIENT_ID", "description": "Allegro app client ID (production)" },
{ "name": "ALLEGRO_CLIENT_SECRET" }
]
}
Name: ^[A-Z][A-Z0-9_]*$, max 64 characters, no ORBITO_ prefix (reserved for the core),
no duplicates; description is optional, max 200 characters.
omm secrets list # module code from ./module.json
omm secrets list --module core/allegro # or the given one
omm secrets set ALLEGRO_CLIENT_SECRET # value from a hidden prompt
OMM_SECRET_VALUE=... omm secrets set ALLEGRO_CLIENT_SECRET # CI, no prompt
omm secrets unset ALLEGRO_CLIENT_SECRET
listshows secrets declared in the latest version plus stored ones, with statusset/missing value/undeclared— never the values.setalso works for a name that is not declared yet (values can be set before the first publish). An empty value is an error.- A new value reaches containers on their next start — no new module version needed.
- Publishing is not blocked by missing values —
omm publish --releaseprints a⚠warning for every declared secret without a value.
How publishing works
POST /developer/publish— ZIP upload; the server readsmodule.json, checks the module card owner and semver, and queues the Docker image build. A draft of the same version is overwritten (retry without bumping the version); published versions are immutable.GET /developer/publish/:imageId— the CLI polls the build status.POST /developer/publish/:imageId/finalize— only with--release: publishing (draft → published); the previously published version becomes deprecated. Server warnings (warnings, e.g. a secret without a value) are printed as⚠.
Authorization: Authorization: Bearer omm_... header (publish token, managed in the
developer panel or by omm login/omm logout).
Orbito Core endpoints used
| Command | Endpoint |
|---|---|
login --core |
POST /auth/signin, GET /users/me |
| (automatic refresh) | POST /auth/refresh |
company list / company use |
GET /users/me |
company dev-token |
PUT /companies/:id/dev-token |
install |
POST /m/:moduleCode/enable (org_name, withDependencies: true) |
update |
POST /m/i/:id/update; same version: POST /m/i/:id/reload |
instances |
GET /m/instances |
logs |
GET /m/i/:id/logs (forDay, since), --container: GET /m/i/:id/container-logs |
problems |
GET /problems?moduleCode= |
call |
POST /m/i/:id/api/:method |
automation list / get |
GET /automations (isEnabled, query, limit), GET /automations/:id |
automation create / update |
POST /automations?strict=true, PUT /automations/:id?strict=true |
automation enable / disable |
PUT /automations/:id ({ isEnabled }) |
automation delete / duplicate |
DELETE /automations/:id, POST /automations/:id/duplicate |
automation elements / element |
GET /automations/editor/elements |
automation runs / run |
GET /automations/runs (automationId, status, eventValue, limit), GET /automations/runs/:runId |
automation var list / get / set |
GET /automations/vars, GET / PUT /automations/vars/:key |
Requests carry Authorization: Bearer <jwt> and the working company in x-company-id.
Dependencies
Dependencies
| ID | Version |
|---|---|
| commander | ^12.1.0 |
| yazl | ^2.5.1 |