Command line¶
Document operations have SDK and REST twins; the browser uses the same API.
Command |
Does |
REST |
|---|---|---|
|
Prints the version (and the codename, once registered). |
|
|
Starts the app and the API on port 8766, or the next free port, which it prints; with a file, Save writes back to it. |
|
|
Launches the native Electron window and its server; passes FILE to the desktop shell. Quitting the window ends the command. |
the REST API underneath |
|
Serves the tools to an agent over MCP on standard input and output; see working with agents. |
the REST API underneath |
|
Converts between the file formats; |
|
|
Standard bond lengths and angles for every molecule, the drawing’s arrangement kept; in place unless |
|
|
Lays the whole reaction scheme out as papers draw it, its steps and reactions kept (Tidy scheme); a scheme it cannot lay out is left, with the reason and exit status 3. |
|
|
3D structures (ETKDG, then MMFF94) with the drawn stereochemistry checked, kept in the document; in place unless |
|
|
Relaxes 3D structures with FIRE on MMFF94 or UFF, the drawn stereochemistry checked; a |
|
|
Writes the inputs and submits them to vibe-scheduler as one group, embedding what has no 3D structure; the jobs and runs are saved in DOC. |
|
|
The document’s runs in vibe-scheduler with their state, group and where each result is: the queue’s directory and, for a container, its file. |
|
|
Cancels a run that has not finished. |
|
|
Cancels the runs of a group that have not finished; finished runs are left alone. |
|
|
Reviews the document’s staged recipes: each stage per species as vibe-qc would run it, with refusals and what the operator gives at launch. |
|
|
Saves a staged recipe (the publication baseline, or a recipe as JSON), replacing one with the same id; in place unless |
|
|
Removes a recipe. |
|
|
Compiles a recipe into a vibe-scheduler campaign in a new directory, records it on the recipe and prints the |
|
|
Electronic reaction reports from verified, accepted campaign artifacts, with balanced coefficients and retained review provenance. |
|
|
Each stage’s process state in vibe-scheduler, its attempts and retries, and its scientific acceptance. Needs vibe-queue. |
|
|
Authorises the next attempt of a failed node, recorded as its retry; the next |
|
|
Renders a species’ start and accepted stages in one orientation from the campaign’s verified artifacts: an aligned QVF per geometry with its trajectory, |
|
|
Shows a species in vibe-viewer as a QVF: through vibe-viewer’s hand-off when it started vibe-sketcher, else with |
|
|
Renders the scheme or the structures as SVG, EPS or EMF, or as PNG or PDF with the publication extra; |
|
|
Renders every document in every format into DIR as |
the same routes, per document |
|
Import a verified output onto a recorded run; an optimisation’s geometry comes back to the species, and |
|
|
Export a result’s |
|
|
A run’s NMR shieldings per set of equivalent nuclei and, against a reference run at the same level of theory, its shifts; JSON or a CSV, Markdown or LaTeX line list. See results. |
|
|
Places the shifts as text beside the atoms of the species’ drawn structure; in place unless |
|
|
Report explicit source results; optional coefficients and SVG/QVF/CSV/Markdown/LaTeX exports. |
|
|
Marks atoms of a species (numbered as in the report) in a palette colour for the canvas and figures, or removes marks; in place unless |
|
|
Draws groups such as Ph, Boc or OTf as their label, or their atoms again, without changing the structure; in place unless |
|
|
Generates a nanotube, graphene flake, nanoribbon or fullerene from its parameters and adds it as a species with its 3D atoms; creates DOC if needed, in place unless |
|
|
Puts a picture of a nanostructure species on the canvas as one object; in place unless |
|
|
Moves a labelled structure onto an anchor of a nanostructure’s picture, so figures print them as one; in place unless |
|
|
Draws an electrode half-reaction (a participant is |
|
|
Each reaction’s atom and charge balance with its electrons; exits 1 when one does not balance. |
|
|
Draws a TLC plate beside the drawing from shapes and text, a spot per Rf; in place unless |
|
|
Draws a laboratory apparatus pictogram (flask, conical-flask, beaker, condenser, separatory-funnel, column, vial, hotplate, three-electrode-cell, two-compartment-cell, potentiostat, tube-furnace, gas-cylinder, uv-lamp) from shapes; in place unless |
|
|
Makes a species of a labelled structure by replacing each attachment label (CNT, Au, …) with the cap, which it records; in place unless |
|
|
The drawing’s R-group cores, bracketed groups and labelled structures (with their labels and capped species) as CXSMILES, and each R-group’s substituents and conditions. See the document format. |
|
|
Each species’ CIP descriptors (R/S, r/s, E/Z), its undefined stereocentres and double bonds, and its enhanced-stereo groups. See the app. |
|
|
Writes the descriptors into the drawing as labels, or removes them; in place unless |
|
|
Enters a reaction’s amounts for its stoichiometry table (mmol, mass_mg, volume_ml with density_g_ml or concentration_mol_l, equivalents, coefficient), replacing earlier ones; in place unless |
|
|
The worked table: molar masses, equivalents, mmol, mass, volume, limiting reactant, theoretical and isolated yields, as JSON or a CSV, Markdown or LaTeX table. |
|
|
Formula, masses, elemental analysis and calculated descriptors per species as a CSV, Markdown or LaTeX table; see the app. |
|
|
Places the species’ formula, molar mass and analysis (or the chosen fields) as text under its structure; in place unless |
|
|
Formula, masses, elemental analysis, descriptors, charge, multiplicity, identifiers and checked name per species, and the reactions. For a finished QVF job container, its result too: the job, its status, the energy and the conformer the result geometry became. |
|
|
The checked name of a structure; exit status 3, and the engine’s unchecked suggestion on standard error, when there is none. |
in the report |
|
Checks documents; prints every problem. |
|
|
Prints the document JSON schema. |
|
|
Lists the input writers. |
|
|
Writes a job’s input. |
|
|
Shows a reaction’s atom mapping and writes its nudged-elastic-band inputs (reaction paths); an ambiguous mapping or an inexpressible specification exits with status 3 and the reasons. |
|
|
Writes species with one writer, the specification from the options or |
|
Discover options and select species¶
Run vibe-sketcher --help for the command list and, for example,
vibe-sketcher input --help for a command’s complete options. Use
vibe-sketcher info DOCUMENT.vsk --json to discover species IDs before selecting
one with --species; IDs belong to the document, not to a chemical name.
vibe-sketcher writers --json lists registered writers and their supported
fields and tasks.
Quote SMILES and reaction SMILES in the shell, especially strings containing
>, parentheses or brackets. For example:
vibe-sketcher convert 'CC(=O)O.CCO>>CC(=O)OCC.O' --from smiles -o reaction.vsk
clean and embed update the input document unless you supply -o.
input --embed prepares missing geometries for input generation without saving
them back to the document; use embed separately when you want to retain them.
submit records jobs and runs in its input document. Keep an editable master
and choose separate destinations for figures and exchange formats.
Convert files and text¶
convert infers the input format from a file’s suffix. For literal text,
provide --from, and quote the string:
vibe-sketcher convert 'CCO' --from smiles -o ethanol.vsk
vibe-sketcher convert ethanol.vsk -o ethanol.sdf
vibe-sketcher convert ethanol.vsk --to smiles -o ethanol.smi
--to explicitly selects the output format; otherwise the output suffix
selects it (.smi means SMILES). Keep the suffix consistent with the requested
format so another program can recognize the file. convert prepares the
supported representation; it does not generate missing 3D coordinates.
For XYZ output, embed first and use input --program xyz as described in
file formats.
Exit statuses and result protection¶
Exit status: 0 on success, 1 for an invalid document, unreadable input or a missing drawing library, 2 for a usage error (an unknown job, species or writer included), 3 when a writer or an exporter refuses. The REST side is mapped in the REST API.
The server serves its OpenAPI description at /openapi.json, so an agent
can read the contract instead of guessing it.
QVF results are imported as structures; calculation payloads are not kept.
A finished QVF job container opens with its drawing, the result geometry as
a new conformer of the job’s species and the energy (vibe-sketcher info).
Commands refuse to write over such files (exit status 3). Use --output with
a different QVF or VSK destination. Native sketch QVF files can be saved in
place when their data is reproducible from the stored sketch. Before submit,
convert an imported result to a new sketch file: submission needs to save run
records in its input document, so it refuses protected files before starting
any jobs.
Browser server and file-backed editing¶
vibe-sketcher serve draft.vsk --port 8766 --open
If draft.vsk exists, the server loads it; if not, it opens an empty document
and creates the file on the first Save. The parent directory must already
exist. Use a native VSK or supported QVF document here. To open another
chemistry format, use the browser’s Open action or convert it to VSK first.
Without --port, the server tries ports 8766 through 8775. With an explicit
port it refuses an occupied port instead of choosing another. Use the printed
address for clients. Ctrl+C stops the server; save wanted edits first because
its open-document store is held in memory.
A browser upload and a file named on the server command line have different save behavior: uploads download copies, while a file-backed document can save to its original path. Protected QVF results still require a different output file. The app guide describes browser and desktop saving.
Desktop launch¶
With a source installation, vibe-sketcher desktop works from any directory.
The first launch installs the reviewed Electron runtime; later launches
check it and repair a missing, damaged or stale runtime. An installed wheel
alone has no electron/ directory: run ./scripts/install.sh in a source
checkout and use its .venv/bin/vibe-sketch.
The launcher selects port 8766 or one of the next nine free ports. An explicit
--port must be free. It records its Python interpreter for later desktop
launches, and passes the current directory, optional file and version to
Electron in a private temporary file. The temporary file is removed when
the window exits or the command is interrupted. Ctrl+C stops Electron, whose
main process owns the server lifecycle.
On Linux, run as a regular user. --no-sandbox is a Linux-only escape hatch
for restricted environments and prints a warning; running as root is refused
even with that flag. Missing Linux libraries preserve the installer’s
diagnostic and exit status 2. Other Electron failures retain their status,
with signals mapped to 128 plus the signal number.
vibe-sketcher return-geometry DOC RETURNED.qvf --document-id KEY --output UPDATED.vsk
appends a checked viewer geometry without replacing the drawing. Use the same key
with view --document-id KEY; omit it only when the document is unchanged since
sending. REST accepts the archive as base64 in data at
POST /api/documents/{id}/geometry-return; MCP exposes return_geometry.
The browser’s Import returned geometry button uses that same endpoint.
Named reactions¶
See the compound, fragment and named-reaction library for the searchable picker, editable examples, explicit unfinished scaffolds, source coverage and matching SDK, CLI, REST and MCP operations.