Command-line reference

The v_ase executable has three command groups: gui, remote, and api. Run v_ase COMMAND --help for the parser generated by the installed release.

Top-level syntax 

v_ase [-h] [--version] {gui,remote,api} ...

For ASE-GUI-style convenience, a non-option first argument is normalized to gui:

v_ase POSCAR
# equivalent to
v_ase gui POSCAR

`v_ase gui`

v_ase gui [FILE] [OPTIONS]

With no file, the command opens an empty editable workspace. A local file opens in View unless --interactive is present. HOST:/absolute/path starts the backend on an SSH host and renders through a local browser.

Input and output

Option	Meaning
`FILE`	Optional structure, trajectory, `.vase`, project HTML, volumetric file, or remote target
`-i INDEX`, `--index INDEX`	ASE read index; `:` all frames (default), `-1` last, integer one frame
`-o PATH`, `--output PATH`	Write the finalized edited structure
`--format FORMAT`, `--input-format FORMAT`	Override input reader inference
`--output-format FORMAT`	Override ASE output format inference
`–volumetric-precision fp32	fp64`

Common format aliases include POSCAR, XDATCAR, vasprun.xml, lammpstrj, data, traj, xyz, extxyz, CHG, CHGCAR, PARCHG, LOCPOT, ELFCAR, cube, xsf, vase, and html. Raw ASE format names such as vasp-xml and lammps-data also work.

Browser and lifecycle

Option	Meaning
`--port PORT`	Bind a predetermined loopback port instead of selecting a free one
`--no-browser`	Do not launch a browser; print the URL
`--no-block`	Return from document waiting but keep the local process/server until interrupted
`--stream-frames`	Transfer trajectory coordinates per frame instead of preloading a browser cache

The server remains bound to 127.0.0.1. In the default blocking mode, closing the final connected v_ase browser page finalizes output and releases the process.

Initial display and edit mode

Option	Meaning
`--show-bonds`	Start with inferred bonds visible (default)
`--hide-bonds`	Start with bonds hidden
`--hide-cell`	Start with the unit cell hidden
`--hide-axes`	Start with axes hidden
`--interactive`	Start in Edit with mutation, history, constraints, and relaxation

Projects and imported visual settings may provide more specific restored state.

Machine-readable collaboration

--cli suppresses automatic browser launch and prints:

one JSON discovery handshake as the first stdout line;
later v_ase.collaboration.v1 NDJSON change events.

It does not parse natural language or accept commands on stdin. An external agent sends structured JSON through the handshake’s loopback command_url, normally using v_ase api. Status text is written to stderr so stdout remains machine-readable.

v_ase gui structure.vasp --interactive --cli

Open human_url from the handshake to work in the same live document.

Remote paths and runtimes 

Start a remote session:

v_ase gui USER@HOST:/absolute/path/to/trajectory.extxyz

The same v_ase release must be installed remotely. If a non-interactive SSH shell does not find the intended executable, select it for one launch:

v_ase gui physics:/data/POSCAR \
  --remote-python /home/user/miniconda3/envs/vase/bin/python

`v_ase remote`

Persist the exact Python executable for a host string:

v_ase remote configure physics \
  --python /home/user/miniconda3/envs/vase/bin/python

v_ase remote show
v_ase remote show physics
v_ase remote remove physics

The one-launch --remote-python value takes priority over the saved mapping. The configuration stores only host names and absolute Python paths in the local user configuration area; it does not copy SSH credentials or scientific files.

`v_ase api`

v_ase api COMMAND_URL METHOD [OPTIONS]

COMMAND_URL comes from the first line of v_ase gui ... --cli. Supported methods are:

Method	Purpose
`ready`	Wait for the live browser/document bridge
`schema`	Read a compact operation/export index or one focused typed contract
`describe`	Read one exact semantic state profile and current revision
`capabilities`	Read a compact live feature/catalog index; request full only for integration diagnostics
`documents`	List workspace documents
`activate`	Activate one document before subsequent commands
`newDocument`	Create an empty workspace document
`apply`	Apply display/selection/camera/structure operations
`render`	Capture the exact image-rendering path
`export`	Generate a named scientific/media/project export

Parameters

Pass a JSON value directly or from a UTF-8 file:

v_ase api "$COMMAND_URL" schema --operation-schema move-selection
v_ase api "$COMMAND_URL" describe --profile structure --include-positions

v_ase api "$COMMAND_URL" apply \
  --params-file command.json

Bare schema and describe default to compact summary responses. Schema shortcuts are repeatable --operation-schema NAME, --export-schema FORMAT, and --schema-method apply|describe|render; use --full-schema only for integration audits. Describe profiles are summary, structure, appearance, bonding, render, analysis, and full, with opt-in --include-positions, --include-properties, and --include-overrides. CLI apply responses default to summary plus mutation.changedPaths; choose another with --response-profile.

--timeout SECONDS defaults to 300 and is capped at 1800.

Saving returned data

render and export can return a data URL. Decode it atomically to a file:

v_ase api "$COMMAND_URL" render \
  --params-file render.json \
  --save figure.webp

--save refuses to replace an existing file. Add --force only after the destination is verified and replacement is intended.

Without --save, render/export dataUrl values are omitted from stdout by default so Base64 does not enter terminal or AI context. Use --print-data-url only when an integration explicitly requires the raw URL.

Revision-safe mutation

Read describe, take its current collaboration revision, and include that as expectedRevision in the next apply mutation. If a researcher edits the GUI first, the stale command is rejected before mutation; re-read state and plan from the newer revision.

The complete workflow and JSON shape are in AI-agent integration.

Exit codes and errors 

Parser/JSON errors and failed commands return a nonzero code and write a concise diagnostic to stderr. api --params reports JSON line and column. A --save failure does not expose binary payload on stdout as ordinary terminal text.

If startup detects a NumPy/SciPy/matscipy binary mismatch, it reports a direct environment repair command before trying to interpret the source file. See Troubleshooting.