amide
Molecular dynamics in your terminal: amide opens a PDB trajectory as a shaded pixel molecule you can rotate, play, and step through frame by frame.
uv tool install amide
amide view protein.pdb
Or pip install amide. Python 3.11 or newer. The wheel is pure Python with one dependency (typer).
- Version: 0.3.0
- License: GPL-3.0-or-later
- Package: https://pypi.org/project/amide/
- Source: https://github.com/CyrusCorrell0/amide
- Site: https://amide.cyruscorrell.com/
The first view downloads the viewer binary for your platform from the GitHub release v0.3.0, verifies its sha256 against checksums.txt from the same release, and caches it at $XDG_CACHE_HOME/amide/tui/0.3.0/ (default ~/.cache/amide/tui/0.3.0/). Later runs are instant. amide view with no path opens a file picker on the current directory.
Commands
| Command | What it does |
|---|---|
amide |
Prints the banner. Static, with no escape codes, when stdout is not a terminal. |
amide view [PATH] |
Opens the viewer on a PDB file, or the file picker on a directory. PATH defaults to .. Needs an interactive terminal. |
amide info <PATH> [--json] |
Prints frames, atoms, chains, residues and extent of a PDB file. No terminal, network or viewer needed. JSON when --json is passed or stdout is not a terminal. |
amide index [PATH] [--json] |
Finds every PDB file under PATH and adds it to the global index. PATH defaults to .. |
amide search [FILTERS] [--sort KEY] [-r] [--json] |
Searches the index. Opens the search screen on a terminal. JSON when --json is passed or stdout is not a terminal. |
amide doctor [--json] |
Checks everything view needs and prints the fix for each failure. Makes no network requests. |
amide -v, amide --version |
Prints amide 0.3.0. |
amide -h, amide --help |
Prints help with examples. Under 100 ms. |
amide info
$ amide info protein.pdb
protein.pdb
frames 3
atoms 1,204 per frame (no hydrogens)
chains A, B
residues 150
extent 42.1 x 38.7 x 55.2 A
Atom, hydrogen, chain, residue and extent figures come from the first frame. --json prints the same as one object with stable keys, in this order:
{
"path": "protein.pdb",
"id": null,
"title": null,
"frames": 3,
"atoms": 1204,
"hydrogens": 0,
"chains": [
"A",
"B"
],
"residues": 150,
"extent": [
42.1,
38.7,
55.2
]
}
id is the four-character code from the HEADER record and title the text of the TITLE records, joined across lines. MD output usually has neither, so both are null there, and the human output prints them only when present.
amide index
amide index ./runs walk ./runs, summarize every .pdb, store the rows
amide search open the search screen on everything indexed
amide search 1ubq frames:2.. start it narrowed: words match id, title or path
amide search --sort frames -r --json the same rows as JSON, for pipes and agents
amide index walks PATH, runs amide info on every .pdb file, and keeps the rows in one JSON file at $XDG_CACHE_HOME/amide/index.json (default ~/.cache/amide/index.json). A row has the keys of amide info --json plus size, modified and indexed.
Unchanged files are skipped by size and modification time, so a second run over the same tree is instant. Files that vanished from under PATH are removed. Windows debug symbols are also .pdb files; they have no ATOM records, so they are counted as skipped instead of failing the run. The exit code is 0 even when files were skipped.
The report is two lines: the counts, then where the index lives. --json prints the same counts as one object.
$ amide index C:\runs
indexed 1,204 files under C:\runs: 1,180 new, 20 updated, 4 unchanged, 2 skipped (no ATOM records), 0 removed
~/.cache/amide/index.json
amide search
On a terminal, amide search opens the search screen: the matching files on the left, the highlighted one drawn and slowly spinning on the right, its facts underneath.
+-- amide search frames:2.. ------------------------------------------------------+
| PDB FRAMES ATOMS CHAINS | +-------------------------------------+ |
| | | | |
| 1UBQ 1 660 A | | (half-block pixel | |
| > - 500 1204 AB | | molecule, spinning | |
| 2LYZ 1 1001 A | | slowly) | |
| - 20 3312 ABCD | | | |
| | +-------------------------------------+ |
| | traj.pdb |
| | 500 frames 1,204 atoms AB |
| | 150 residues 42.1 x 38.7 x 55.2 |
| | 18.2 MB C:\runs\prod\traj.pdb |
| type to filter enter open c copy path s sort: frames r reverse esc quit |
+-----------------------------------------------------------------------------------+
Typing narrows the list on id, title and filename. enter opens the viewer on the highlighted file, and q in the viewer comes back to the list with the cursor where it was. See "Keys in search" below.
Filters are key:value tokens. They need no quoting in any shell, and all of them must match:
| Token | Matches |
|---|---|
word |
id, title or path contains word, case-insensitive |
id:1ubq title:lysozyme path:runs |
that field contains the value |
chains:A |
the chain list contains A |
frames:3 |
equals |
frames:2.. frames:..10 frames:2..10 |
at least, at most, between |
Numeric keys: frames, atoms, hydrogens, residues, size. --sort KEY orders the rows by path (the default), id, frames, atoms, hydrogens, residues, size or modified, and -r reverses. Rows without an id sort last.
--json, or stdout that is not a terminal, prints the matching rows as a JSON list, [] when nothing matches. An unknown key, a non-numeric value or an unknown sort key exits 2 and names the valid ones. An empty index exits 2:
amide search: nothing indexed yet; run `amide index <directory>`
amide doctor
$ amide doctor
ok amide 0.3.0, python 3.12.4
ok platform windows/amd64 is supported
ok viewer 0.3.0 cached at C:\Users\you\.cache\amide\tui\0.3.0\amide-tui.exe
ok terminal is interactive (120x40)
A failing check prints fail and a second line starting fix:. Exit 0 when every check passes, 1 otherwise. --json prints {"ok": bool, "checks": [{"name", "ok", "detail", "fix"}]}.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Done. |
| 2 | Usage error, or PATH does not exist. For search, a bad filter or an empty index. |
| 3 | The viewer is unavailable (no build, offline, checksum mismatch). |
| 4 | view was run without an interactive terminal. |
| 5 | The file has no ATOM or HETATM records (not a PDB amide can read). |
| 130 | Interrupted with ctrl+c. |
doctor also exits 1 when any check fails. Errors are one line on stderr, start with amide <command>:, and end with the next step when there is one.
Environment
| Variable | Effect |
|---|---|
AMIDE_TUI |
Path to a viewer binary to use instead of downloading one. |
XDG_CACHE_HOME |
Cache root for the viewer binary and the index. Default ~/.cache. |
AMIDE_NO_ANIMATION |
Print the banner in one go, no flourish. |
NO_COLOR |
Honoured. Also prints the banner in one go. |
CI |
Prints the banner in one go, and makes view exit 4. |
AMIDE_GRAPHICS |
none, kitty, sixel or iterm2. Overrides terminal detection for the pixels canvas. |
Platforms
Viewer builds: darwin/arm64, darwin/amd64, linux/amd64, linux/arm64, windows/amd64. Not windows/arm64. amide info runs everywhere Python does.
Keys in the viewer
| Action | Keys |
|---|---|
| Rotate | arrows, h j k l, or w a s d |
| Pan | H J K L |
| Zoom | + - |
| Play or pause | space |
| Previous or next frame | , . |
| Slower or faster | [ ] |
| Cycle render mode (space fill, ball and stick, wireframe, cartoon) | m |
| Show or hide hydrogens | e |
| Toggle side panel | tab |
| Cycle canvas: half block, quadrant, braille, sextant, pixels | p |
| Toggle cartoon | c |
| Rock the view | r |
| Reset view | 0 |
| Back to picker or search | q, esc |
| Quit | ctrl+c |
Graphics
p cycles the canvas from coarse to fine. Half block, quadrant, braille and sextant draw with text and work in any true-colour terminal. Sextant needs a font with Symbols for Legacy Computing, such as Cascadia Code. Pixels draws a real image and needs a terminal that speaks an image protocol; elsewhere p skips it.
| Protocol | Terminals |
|---|---|
| kitty | kitty, WezTerm, Ghostty, Konsole |
| iTerm2 | iTerm2 |
| sixel | Windows Terminal 1.22 or later, VS Code 1.101 or later, foot, mlterm |
Under tmux the viewer stays on text canvases.
Over SSH only iTerm2 and kitty forward the variables the viewer reads. For the others, set AMIDE_GRAPHICS on the remote shell.
Depth cues: far atoms fade, overlaps get a dark edge, near atoms are drawn larger.
Keys in search
| Action | Keys |
|---|---|
| Filter | type |
| Move | arrows, j k |
| Open in the viewer | enter |
| Copy the file path | c |
| Cycle sort (path, id, frames, atoms, hydrogens, residues, size, modified) | s |
| Reverse sort | r |
| Quit | esc, q |
For agents
Do not run amide view in a captured shell. It is a full-screen program. Off a terminal it refuses with exit 4 instead of hanging, but it never shows you anything. The same goes for amide search without --json: on a terminal it opens the interactive search screen, like view.
Paths, in order of preference:
amide info <file> --jsonto learn what is in a file. It is non-interactive, offline, and cheap.- Hand
amide view <file>to the person, to run in their own terminal. amide index <dir>once, thenamide search frames:2.. --jsonto find files by frames, id or title without opening each.amide doctor --jsonwhen any of the above fails and the cause is unclear.
Decision rule: amide reads PDB files only. Convert other formats (.gro, .xtc, .dcd, .cif) to PDB first, for example with MDAnalysis or gmx trjconv, then run amide on the result.
What to do on each exit code:
| Code | Do this |
|---|---|
| 2 | Fix the path or the arguments. stderr names the problem. From search, fix the filter, or run amide index <dir> when nothing is indexed yet. |
| 3 | The viewer is unavailable to view or search. Retry once online, or set AMIDE_TUI to a local viewer binary. Run amide doctor to see which. |
| 4 | Use amide info instead, or give the view command to the person. |
| 5 | Convert the file to PDB, then retry. |
Verify the install:
amide -v
amide info tests/data/sample.pdb --json
The second line works from a checkout of the source repository. Any PDB file will do elsewhere.
Suggested line for AGENTS.md or CLAUDE.md:
amide: molecular dynamics CLI for PDB trajectories. Install with `uv tool install amide`.
Use `amide info <file.pdb> --json` to inspect a file. `amide view <file.pdb>` is an
interactive terminal viewer: give it to the user, never run it in a captured shell.
Docs: https://amide.cyruscorrell.com/docs.md
Not yet
- PDB only. No other trajectory formats.
- No shell completion.
- No viewer for Windows on arm64.
- No parallel indexing. A first
amide indexover a large tree summarizes one file at a time. - No
amide view <id>. Open a file by id throughamide search. - No watching directories. Run
amide indexagain after files change. - The first
viewneeds the network once. Offline it exits 3; setAMIDE_TUIto a local binary.
Metadata
Release files for amide 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amide-0.3.0.tar.gz | 101.5 kB | Without provenance | Details for amide-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amide-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for amide-0.3.0-py3-none-any.whl |
Total release size: 133.7 kB
Release files / amide-0.3.0.tar.gz
| Download URL | amide-0.3.0.tar.gz |
|---|---|
| Size | 101.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca4d171c46fdf521b39e3a9df6162a5b56f5f1a51e3579c2aebf6e7329c77e3f
|
|
BLAKE2b-256 checksum How to use checksums |
e46b19679fbd1dd5cdba553c347bac3b05a04d6129c626bfd6c2dd97c2581cc1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.5
|
Release files / amide-0.3.0-py3-none-any.whl
| Download URL | amide-0.3.0-py3-none-any.whl |
|---|---|
| Size | 32.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ad03db5ee172cb6c1fdc26dcf28e4995d2ae27a20d37da69b9ae1de8410666d
|
|
BLAKE2b-256 checksum How to use checksums |
e490559cb4c85c2d2f004a62f336b7685323a454e93c8bce53d9752c3478ba3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.5
|
Security for amide 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.