@orbito/omm (1.0.1)
Installation
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/npm install @orbito/omm@1.0.1"@orbito/omm": "1.0.1"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 i -g @orbito/omm
@orbito/omm and @orbito/api-lib are on the public npm registry — no .npmrc or token is needed.
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>.
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 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.
omm instances --json
omm call ping --json
Configuration
~/.config/omm/config.json— publish token per registry (registries) and session per core (cores[url] = { token, expiresAt, email, companyId },core= last used core).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).
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 |
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 |