Skip to content

Command line

Installing the cli extra puts a helmshaker command on your path:

pip install "helmshaker[cli]"

The command covers two jobs: authenticating against TMR or Forge and caching a monomer dictionary, then running the engine (parse, validate, molecular weight, convert) against that cached dictionary. Once a dictionary is cached, the engine commands work offline.

helmshaker <command> [options]

  login          Log in via Forge/Janus, or store a token
  logout         Remove the cached token
  whoami         Show the current identity from the token
  library        Monomer library operations
  parse          Parse a HELM string and summarize it
  validate       Validate a HELM string
  mw             Compute molecular weight and formula
  convert        Convert a HELM string to another notation
  cache          Cache operations

Typical session

helmshaker login --janus-env beta
helmshaker library pull --tmr https://api.core.minerva.roche.com/gateway/tmr-tst \
    --dictionary peptides --version 1.2.0
helmshaker validate 'PEPTIDE1{C.A.A.A.C}$$$$V2.0' --dictionary peptides

Authentication

helmshaker login

Obtains a token and caches it. Defaults to the device-authorization flow, which prints a URL and a code for you to approve in any browser. That works headless and over SSH.

Option Description
--forge FORGE Forge base URL
--janus-env {stable,beta,alpha} Janus environment to authenticate against
--client-id CLIENT_ID OIDC client id, otherwise $HELMSHAKER_JANUS_CLIENT_ID
--token TOKEN Store this token directly instead of logging in
--no-browser Print the login URL instead of opening a browser
--loopback Use the browser-redirect flow instead of the device flow
--redirect-port PORT Port for the loopback redirect

In CI, skip login and set $HELMSHAKER_TOKEN instead.

helmshaker whoami

Prints the identity claims from the cached token. Takes --token TOKEN to inspect a token you supply instead.

helmshaker logout

Deletes the cached token.

Monomer libraries

helmshaker library pull

Fetches a dictionary and caches it on disk. Requires exactly one of --forge or --tmr.

Option Description
--forge FORGE / --tmr TMR Source to fetch from; mutually exclusive, one required
--dictionary DICTIONARY Dictionary name or primary key
--version VERSION Dictionary version; omit for the latest
--token TOKEN Bearer token, otherwise $HELMSHAKER_TOKEN or the cached login
--api-key API_KEY TMR Gravitee API key, otherwise $HELMSHAKER_TMR_API_KEY
--ca-bundle CA_BUNDLE CA bundle for TLS verification
--insecure Disable TLS verification, for internal gateways
--refresh Refetch even when a fresh cache exists

helmshaker library dictionaries

Lists the dictionaries available in TMR. Requires --tmr, and accepts the same --token, --api-key, --ca-bundle and --insecure options as pull.

helmshaker library list

Lists the dictionaries already in the local cache.

helmshaker library show

Prints a cached dictionary. Takes one positional cache key:

helmshaker library show peptides@1.2.0
helmshaker library show peptides@latest

Engine commands

parse, validate, mw and convert each take a HELM string as their single positional argument, and share the library-resolution options below.

Option Description
--dictionary DICTIONARY Cached dictionary to resolve monomers against
--version VERSION Dictionary version
--forge FORGE / --tmr TMR Fetch the dictionary now instead of using the cache
--token TOKEN Bearer token for a live fetch
--permissive Do not fail on unrecognized monomers

helmshaker parse

Parses a HELM string and prints a summary of its polymers and connections.

helmshaker parse 'RNA1{[moe](A)[sp].[moe](U)}$$$$V2.0' --dictionary oligos

helmshaker validate

Validates a HELM string against the dictionary. Exits non-zero when validation fails, so it works as a gate in a pipeline.

helmshaker mw

Computes molecular weight and formula. Needs the chem extra for RDKit:

pip install "helmshaker[chem]"
helmshaker mw 'RNA1{[moe](A)[sp].[moe](U)}$$$$V2.0' --dictionary oligos

Add --smiles to print the assembled SMILES as well.

helmshaker convert

Converts to another notation. --to is required.

helmshaker convert 'RNA1{[moe](A)[sp].[moe](U)}$$$$V2.0' --to fasta --dictionary oligos
Value Output
--to helm HELM, round-tripped
--to fasta FASTA of the natural-analog sequence
--to xna XNA sugar/base/phosphate columns

Cache

helmshaker cache clear

Removes every cached dictionary.

Environment variables

Variable Used for
HELMSHAKER_TOKEN Bearer token, instead of a cached login. Use this in CI
HELMSHAKER_JANUS_CLIENT_ID Default OIDC client id for login
HELMSHAKER_TMR_API_KEY TMR Gravitee API key