CLI reference

The asciichem CLI provides conversion, linting, and round-trip verification. Install via gem install asciichem.

convert

Convert AsciiChem source to an output format.

asciichem convert -i "H_2O" -t mathml
asciichem convert -i "2Na+ + SO_4^2- -> Na_2SO_4" -t cml
asciichem convert -f input.asciichem -t html
echo "H_2O" | asciichem convert -i - -t latex

Options

Flag	Description
`-i, --input`	AsciiChem source text (or `-` for stdin)
`-f, --file`	Read source from a file
`-t, --format`	Output format: `mathml` (default), `text`, `html`, `latex`, `svg`, `cml`

Parsing engine

convert --engine parsanol selects the opt-in Rust-core engine for that invocation (parslet stays the default; the parsanol gem is an opt-in dependency). Without the gem installed, the command exits 6 with install guidance.

asciichem convert -i "2H_2 + O_2 -> 2H_2O" -t text --engine parsanol

The ASCIICHEM_ENGINE environment variable selects the engine for programmatic use and test runs.

convert with input grammars

Since 0.22.0, convert selects the input grammar with --from asciichem|smiles|molfile, and the output targets include model-json, smiles, molfile, and structural-svg:

asciichem convert -i "CCO" --from smiles -t structural-svg
asciichem convert -f ethanol.mol --from molfile -t model-json
asciichem convert -i "CC(=O)OC1=CC=CC=C1C(=O)O" --from smiles -t smiles   # canonical re-emission

Every grammar funnels into the one semantic model, so every output format works regardless of input language. Molfile input may be a file path (multiline text via -f).

resolve

Resolves an identifier into a substance record (networked; cached in your user cache directory). The default source is PubChem; results carry provenance because the citation track emits one bibitem per (substance, source).

asciichem resolve --name aspirin --source pubchem -t model-json
asciichem resolve --cas 50-78-2 --refresh

validate

Offline validation of identifier annotations in a formula:

asciichem validate -i 'H_2O @cas("7732-18-5")'
# cas          7732-18-5                                ok

identity

Derives InChI and InChIKey from the structure itself — offline, via the configured InChI engine (the IUPAC inchi-1 binary; the InChI algorithm is never reimplemented):

asciichem identity -i "CC(=O)OC1=CC=CC=C1C(=O)O" --from smiles
# InChI=1S/C9H8O4/c1-6(10)13-8-5-3-2-4-7(8)9(11)12/h2-5H,1H3,(H,11,12)
# BSYNRYMUTXBXSQ-UHFFFAOYSA-N

asciichem identity -i "..." --engine-bin /usr/local/bin/inchi-1

Without an engine the command exits 5 with install guidance. In Ruby, register one globally:

AsciiChem::Inchi.engine = AsciiChem::Inchi::BinaryEngine.new
AsciiChem::Inchi.identity_for(molecule)

With an engine configured, asciichem lint cross-checks @inchi and @inchikey annotations against the drawn structure (IdentityCrossCheck).

lint

Run chemistry validation checks. Exits 1 if any errors found.

asciichem lint -i "H_2 + O_2 -> H_2O"
asciichem lint -i "crystal[x](a=-1){Na@f(0,0,0)}" -f json

Options

Flag	Description
`-i, --input`	AsciiChem source text
`-f, --format`	Output format: `text` (default) or `json`

JSON output is an array of {severity, message, node} objects.

roundtrip

Parse and re-emit text; exit non-zero if output differs from input.

asciichem roundtrip -i "H_2O"

parse-cml

Parse CML XML and emit AsciiChem text.

asciichem parse-cml -i "<cml xmlns=\"http://www.xml-cml.org/schema\">...</cml>"

version

asciichem version
asciichem --version

Play