authoring-cli

A CLI for SNOMED CT authoring against Snowstorm/authoring-services: concept CRUD, description/relationship/axiom edits, task lifecycle, classification, validation, and real-time task notifications.

Installation

npm install -g authoring-cli

Requires Node.js 24 or newer.

Register the authoring skill with your AI agent

The package ships an authoring guidance skill alongside the commands, so an AI agent driving this CLI knows the parts that aren't discoverable from the usage text — Snowstorm's exactly-one-preferred-synonym-per-dialect save constraint and the atomic set-acceptability --entries fix for it, US/GB spelling-variant modeling, which axiom edits a published axiom does and doesn't allow, and how to run a large batch across sessions without losing track.

authoring-cli install-skill

Installed skill 'authoring-cli' for:
  claude  ~/.claude/skills/authoring-cli  (symlink -> /usr/local/lib/node_modules/authoring-cli/skills/authoring-cli)
  codex   ~/.codex/prompts/authoring-cli.md  (pointer into the installed package)

Restart your agent, then use /authoring-cli.

Registration is a symlink back into the installed package, so npm update -g authoring-cli updates the guidance too — it can't drift out of step with the CLI you have. By default it registers with whichever agents are present on the machine.

| Flag | Effect | |---|---| | --agent claude\|codex\|all | Register for specific agents (comma-separated) instead of the detected ones | | --project | Install into ./.claude/skills/ for this repo rather than your home directory | | --force | Replace an existing registration of the same name |

Nothing is written outside the package until you run this — installing the npm package doesn't touch ~/.claude or ~/.codex on its own.

Unregistering

authoring-cli uninstall-skill        # run this BEFORE npm rm -g authoring-cli

Order matters. npm 7 removed the uninstall lifecycle scripts — preuninstall and postuninstall are never run — so npm rm -g authoring-cli cannot clean up after itself, and by the time the package is gone, so is the command that would have. Unregister first, remove the package second.

If you do it the other way round, nothing breaks: the leftover symlink dangles and agents skip it. A later npm install -g authoring-cli && authoring-cli install-skill silently reclaims it (no --force needed — it's recognizably ours), or you can delete ~/.claude/skills/authoring-cli and ~/.codex/prompts/authoring-cli.md by hand.

uninstall-skill only removes registrations it can recognize as its own: a symlink into some authoring-cli package, a byte-identical copy of the shipped skill, or a generated Codex pointer. A skill directory or prompt you wrote under the same name is reported and left alone unless you pass --force. It takes the same --agent/--project flags, and defaults to checking every supported agent so nothing is left behind.

Sign in

authoring-cli login production
authoring-cli login uat          # the default if you omit the environment
authoring-cli login dev

| Environment | Base host | Aliases | |---|---|---| | production | https://authoring.ihtsdotools.org/ | prod, live | | uat (default) | https://uat-snowstorm.ihtsdotools.org/ | staging | | dev | https://dev-snowstorm.ihtsdotools.org/ | development |

Each environment supplies all three endpoints — IMS at the base host, the terminology server at snowstorm/snomed-ct/ under it, authoring-services at authoring-services/ — plus that environment's IMS session cookie name.

Opens Chrome to your organization's real IMS login page (password, SSO, Google — whatever IMS itself supports). After you complete login there, the session is captured automatically by watching that Chrome profile's own cookie jar for a fresh session cookie — no copy/paste, and no dependence on IMS's serviceReferer redirect actually reaching back to the CLI (that redirect, when it does land, only shows a friendly "you're signed in" page — it's not required for sign-in to complete). If you're already signed in to that environment in Chrome, the existing session is reused and no browser opens at all.

Login prints the endpoints it actually used and where each came from, so a forgotten flag silently falling back to a different environment is visible rather than invisible:

Signed in as Jane Doe. (reused an existing Chrome session — no browser opened.)
  IMS:                https://authoring.ihtsdotools.org/ (production)
  Terminology server: https://authoring.ihtsdotools.org/snowstorm/snomed-ct/ (production)
  Authoring services: https://authoring.ihtsdotools.org/authoring-services/ (production)

Current support: automatic session capture works on macOS with Google Chrome, and on Linux with Chromium/Chrome — including a Termux:X11 proot-distro Debian on Android, where login auto-starts both halves of Termux:X11's GUI stack if nothing is already serving a display: its backend process (termux-x11 :1 &) and, best-effort, the Termux:X11 app itself — no manual open-once needed, provided Termux has been granted Android's "Draw over other apps" permission (Settings → Apps → Termux), a one-time device setting that can't itself be requested from inside the proot. Without that permission granted, the app-start step silently does nothing and the app still needs to already be open by hand, same as before. On any other OS/browser combination, login fails immediately with a message naming the unsupported combination, rather than hanging or failing silently.

logout deletes the locally stored session. It does not sign you out of IMS in Chrome, so a subsequent login will reuse that browser session.

By default the session lives at <current working directory>/.authoring-cli/session.json — not under your home directory. authoring-cli is commonly driven by an AI agent whose filesystem access is confined to one workspace directory, so this means the session simply lands inside whatever workspace the caller is already scoped to, with nothing to configure and nothing touched outside it. Run it by hand from a consistent directory and you get the same persistence across commands as before; run it from a different directory and it's a fresh session there — the same way e.g. git keeps per-repo config alongside the repo rather than in $HOME. login's own output always names exactly where the session file landed.

There's deliberately no automatic fallback to ~/.authoring-cli if the working directory isn't writable — that used to be the default, but a fallback that silently reads whatever session happens to already exist under the real home directory turned out to be actively dangerous: a leftover session there (from another project, or from before this default existed) would otherwise leak into any brand-new workspace that never signed in at all, silently acting on the wrong project instead of reporting "not signed in". If the working directory genuinely isn't writable, login/select-task/etc. fail with a clear message rather than landing somewhere unexpected.

Set AUTHORING_CLI_HOME to force a specific location instead — e.g. a shared session across multiple directories, or an explicit path when the working directory can't be used. It takes priority over the default, and every command reads/writes the session through the same path, so setting it once (e.g. exported alongside the agent's launch environment) covers login, select-task, and everything else with no per-command flag.

Optional flags, for a deployment the named environments don't cover: --ims-endpoint, --terminology-server-endpoint, --authoring-services-endpoint (each overrides just that one value of the selected environment), --cookie-name <name> (override the IMS session cookie name), --chrome-profile <name> (target a specific Chrome profile by its display name or directory name if you have more than one).

Pick a project and task

authoring-cli projects
authoring-cli tasks                                              # your tasks, across all projects
authoring-cli tasks --project PROJ                               # everyone's tasks in PROJ
authoring-cli tasks --project PROJ --mine                        # just yours, in PROJ
authoring-cli tasks --project PROJ --mine --status "In Progress" # ...and only In Progress
authoring-cli tasks --summary                                    # counts by project/assignee/status
authoring-cli select-task --project PROJ --task PROJ-123
authoring-cli current-task

--mine resolves "yours" server-side via authoring-services' own my-tasks endpoint rather than by matching names locally. Without it, --project lists every assignee's tasks and adds an assignee column so you can tell them apart. --status matches case-insensitively. --summary prints counts instead of one line per task, so a long list doesn't have to be tallied by eye. projects, tasks and recover-task all take --json as well.

Once a task is selected, every action command below applies to it automatically — pass --project/--task explicitly on any individual command to override just that call.

Selecting a task also creates its branch if it doesn't have one yet. A task still in status New has no branch — that's the moment the Authoring Workbench would create it, so select-task does the same, and the first edit afterwards doesn't 404.

Creating and recovering tasks

authoring-cli create-task --project PROJ --summary "Model secondary disorders"
authoring-cli recover-task --project PROJ          # list PROJ's deleted tasks
authoring-cli recover-task --project PROJ --task PROJ-123

create-task assigns the task to you and selects it (--assignee/--unassigned and --no-select override that).

There is no delete-task command: deleting the wrong task is easy to get wrong and hard to notice at the moment it matters, so that decision is left to a human in the Authoring Workbench UI rather than something scriptable here. Deleting a task there moves it to status Deleted but leaves the branch and everything authored on it alone — which is what makes recover-task a real undo rather than a re-creation: it takes the task back out of Deleted with its content intact and selects it again, regardless of whether the deletion happened in the UI or (from before this command existed) via this CLI.

Authoring actions

| Command | Purpose | |---|---| | projects | List the projects available to you | | tasks | List tasks, filtered by project/assignee/status, or summarized | | create-task | Create a task and select it | | select-task | Set the task later commands target (creating its branch if needed) | | current-task | Print the locally selected task | | recover-task | List a project's deleted tasks, or bring one back (there is no delete-task — use the Authoring Workbench UI) | | create-concept | Create a new concept | | get-concept | Fetch a concept by ID | | search-concepts | Search by term or ECL expression | | delete-concept | Delete an unversioned concept | | add-description | Add a description | | update-description | Update an unversioned description's term/case significance | | set-case-significance | Set a description's case significance | | set-acceptability | Set/swap dialect acceptability | | delete-description | Delete an unversioned description | | add-relationship | Add a relationship to a class axiom | | remove-relationship (alias: delete-relationship) | Remove an unversioned relationship | | remove-role-group (aliases: delete-role-group, delete-rolegroup) | Remove a whole role group by its attributes | | add-gci-axiom | Add a GCI (general concept inclusion) axiom | | update-axiom / update-gci-axiom | Replace an unversioned axiom's relationships | | delete-axiom / delete-gci-axiom | Delete an unversioned axiom | | set-definition-status | Set PRIMITIVE/FULLY_DEFINED | | inactivate-concept | Inactivate with a reason and optional association | | validate-concept | Read-only pre-save validation check | | get-concepts-for-review | List concepts with pending stated/classified changes | | validate-review-concepts | Validate every concept with pending stated changes, with a pass/issue tally | | classify | Self-healing classification (attaches to a running job, accepts a completed one, or starts fresh) | | classification-status | Read-only classification status | | validate-task | Self-healing task-level (RVF) validation | | validation-status | Read-only validation status | | watch-notification | Block until the next real-time task notification, or timeout | | install-skill (alias: install-skills) | Register the bundled authoring skill with your AI agent | | uninstall-skill (alias: uninstall-skills) | Remove that registration (before npm rm) |

Run the CLI with no arguments for the full usage text, including every flag.

Example

authoring-cli login
authoring-cli create-task --project PROJ --summary "Add hepatic synonyms"
authoring-cli get-concept --id 64572001
authoring-cli add-description --id 64572001 --term "Hepatic structure" --type SYNONYM
authoring-cli validate-review-concepts
authoring-cli classify --wait

Licence

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Copyright 2026 SNOMED International

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.