amina-cli 0.2.1
CLI for AminoAnalytica protein engineering platform
License: Apache-2.0
Requires Python: >=3.11
Keywords: bioinformatics, cli, esmfold, protein, protein-design, proteinmpnn, structure-prediction

# Amina CLI

Command-line interface for [AminoAnalytica](https://aminoanalytica.com) protein engineering tools.

Run protein structure prediction, sequence design, docking, and analysis directly from your terminal.

## Installation

```bash
pip install amina-cli
```

Requires Python 3.11+

## Quick Start

```bash
# 1. Set your API key
amina auth set-key "ami_your_api_key"

# 2. List available tools
amina tools

# 3. Run a tool
amina run esmfold --sequence "MKFLILLFNILCLFPVLAADNH" -o ./results/
```

Get an API key at [app.aminoanalytica.com/settings/api](https://app.aminoanalytica.com/settings/api)

## Commands Overview

| Command | Description |
|---------|-------------|
| `amina auth` | Manage API key authentication |
| `amina init` | Initialize project resources (Claude Code skills) |
| `amina tools` | List available tools and view parameters |
| `amina run <tool>` | Run a computational biology tool |
| `amina jobs` | Manage background jobs |
| `amina version` | Show CLI version |

---

## Authentication

```bash
# Set API key (required before running tools)
amina auth set-key "ami_your_api_key"

# Check authentication status
amina auth status

# Link CLI outputs to a web conversation
amina auth session <conversation_id>

# Unlink session
amina auth session --unlink

# Remove stored credentials
amina auth logout
```

---

## Claude Code Integration

Install Amina skills to help Claude Code assist with protein engineering tasks.

```bash
# Install skills to .claude/skills/ in your project directory
amina init claude-skills
```

After installing, run `/amina-init` in Claude Code to get started.

The skills teach Claude Code how to:
- Use the Amina CLI effectively
- Run structure prediction, sequence design, and docking tools
- Interpret results and suggest next steps

---

## Discovering Tools

```bash
# List all available tools
amina tools

# Filter by category
amina tools --category folding
amina tools --category design
amina tools --category interactions
amina tools --category analysis
amina tools --category properties
amina tools --category utilities

# Search for tools
amina tools --search dock
amina tools --search glyco

# View tool parameters and usage
amina tools esmfold
amina tools proteinmpnn

# List all categories
amina tools categories
```

---

## Running Tools

```bash
# Basic usage
amina run <tool> [OPTIONS] -o ./output/

# Run in background (returns immediately)
amina run esmfold --sequence "MKTV..." -o ./output/ --background

# Set custom job name
amina run esmfold --sequence "MKTV..." -o ./output/ --job-name my_protein

# Get help for any tool
amina run esmfold --help
amina run proteinmpnn --help
```

---

## Managing Jobs

Background jobs continue running on the server while you work locally.

```bash
# List recent jobs
amina jobs list
amina jobs list --limit 50
amina jobs list --json

# Check job status
amina jobs status <job_id>
amina jobs status job1 job2 job3
amina jobs status <job_id> --json

# Wait for jobs to complete
amina jobs wait <job_id>
amina jobs wait job1 job2 --timeout 7200

# Download results from a completed job
amina jobs download <job_id> -o ./results/
```

---

## Available Tools

### Folding

Predict 3D protein structures from sequences.

| Tool | Command | Description |
|------|---------|-------------|
| ESMFold | `amina run esmfold` | Fast structure prediction from sequence |
| Boltz-2 | `amina run boltz2` | Predict protein/ligand/nucleic acid complexes |
| OpenFold3 | `amina run openfold3` | Predict structures of proteins, RNA, DNA, ligands |
| Protenix | `amina run protenix` | AlphaFold3 structure prediction |

**Examples:**

```bash
# ESMFold from sequence
amina run esmfold --sequence "MKFLILLFNILCLFPVLAADNH" -o ./results/

# ESMFold from FASTA file
amina run esmfold --fasta ./protein.fasta -o ./results/

# Boltz-2 with ligand
amina run boltz2 --sequence "MKTV..." --ligand "CCO" -o ./results/

# Boltz-2 multi-chain complex
amina run boltz2 --sequence "CHAIN_A_SEQ" --sequence "CHAIN_B_SEQ" -o ./results/

# OpenFold3 protein-DNA complex
amina run openfold3 --sequence "MKTV..." --dna "ATCGATCG" -o ./results/
```

---

### Design

Generate and optimize protein sequences.

| Tool | Command | Description |
|------|---------|-------------|
| ProteinMPNN | `amina run proteinmpnn` | Design sequences for a backbone structure |
| RFDiffusion | `amina run rfdiffusion` | Generate novel protein backbones |
| ESM-IF1 | `amina run esm-if1` | Inverse folding - sequences from structure |
| Protein-MC | `amina run protein-mc` | Monte Carlo sequence optimization |

**Examples:**

```bash
# ProteinMPNN sequence design
amina run proteinmpnn --pdb ./structure.pdb --num-sequences 10 -o ./results/

# ProteinMPNN with fixed positions
amina run proteinmpnn --pdb ./structure.pdb --fixed "A10,A15,A20" -o ./results/

# RFDiffusion unconditional generation
amina run rfdiffusion --mode unconditional --length 100 --num-designs 5 -o ./results/

# RFDiffusion binder design
amina run rfdiffusion --mode binder-design --input ./target.pdb --hotspots "A30,A35" -o ./results/

# ESM-IF1 inverse folding
amina run esm-if1 --pdb ./structure.pdb --chain A --num-samples 5 -o ./results/

# Protein-MC optimization
amina run protein-mc --sequence "MKTV..." --temperature 0.01 --num-steps 100 -o ./results/
```

---

### Interactions

Molecular docking, binding site prediction, and glycosylation analysis.

| Tool | Command | Description |
|------|---------|-------------|
| DiffDock | `amina run diffdock` | Diffusion-based molecular docking |
| AutoDock Vina | `amina run autodock-vina` | Classical molecular docking |
| DockQ | `amina run dockq` | Assess docked complex quality |
| P2Rank | `amina run p2rank` | Predict ligand-binding sites |
| Interface Identifier | `amina run interface-identifier` | Identify interface residues between chains |
| PeSTo | `amina run pesto` | Predict protein-protein/DNA/RNA/ligand interactions |
| LMNgly | `amina run lmngly` | N-linked glycosylation prediction |
| EMNGly | `amina run emngly` | ESM-1b based N-glycosylation prediction |
| ISOGlyP | `amina run isoglyp` | O-linked glycosylation prediction |
| Glycosylation Ensemble | `amina run glycosylation-ensemble` | Combined N/O-glycosylation prediction |

**Examples:**

```bash
# DiffDock with SMILES ligand
amina run diffdock --protein-pdb ./protein.pdb --ligand-smiles "CCO" --samples 10 -o ./results/

# DiffDock with SDF ligand file
amina run diffdock --protein-pdb ./protein.pdb --ligand-sdf ./ligand.sdf -o ./results/

# AutoDock Vina docking
amina run autodock-vina --protein-pdb ./protein.pdb --ligand-smiles "CCO" --exhaustiveness 16 -o ./results/

# P2Rank binding site prediction
amina run p2rank --pdb ./protein.pdb -o ./results/

# DockQ quality assessment
amina run dockq --model-pdb ./model.pdb --reference-pdb ./reference.pdb -o ./results/

# Glycosylation prediction
amina run glycosylation-ensemble --fasta ./protein.fasta -o ./results/
```

---

### Analysis

Structural comparison and property analysis.

| Tool | Command | Description |
|------|---------|-------------|
| RMSD Analysis | `amina run rmsd-analysis` | Calculate RMSD with active site support |
| Simple RMSD | `amina run simple-rmsd` | Quick backbone RMSD calculation |
| US-Align | `amina run usalign` | TM-score structural alignment |
| SASA | `amina run sasa` | Solvent accessible surface area |
| Hydrophobicity | `amina run hydrophobicity` | Hydrophobic residue distribution |
| Surface Charge | `amina run surface-charge` | Electrostatic surface analysis |
| MMseqs2 Cluster | `amina run mmseqs2-cluster` | Sequence clustering |

**Examples:**

```bash
# Simple RMSD calculation
amina run simple-rmsd --mobile ./model.pdb --target ./reference.pdb -o ./results/

# RMSD with active site focus
amina run rmsd-analysis --main ./model.pdb --reference ./reference.pdb --active-main "A:50,A:55,A:60" -o ./results/

# US-Align TM-score
amina run usalign --structure1 ./model.pdb --structure2 ./reference.pdb -o ./results/

# SASA calculation
amina run sasa --pdb ./protein.pdb -o ./results/

# Surface charge analysis
amina run surface-charge --pdb ./protein.pdb -o ./results/

# Sequence clustering
amina run mmseqs2-cluster --fasta ./sequences.fasta --identity 0.5 -o ./results/
```

---

### Properties

Sequence-based property prediction.

| Tool | Command | Description |
|------|---------|-------------|
| AminoSol | `amina run aminosol` | Predict E. coli solubility |
| ESM2 Embedding | `amina run esm2-embedding` | Extract protein embeddings |

**Examples:**

```bash
# Solubility prediction from FASTA
amina run aminosol --fasta ./proteins.fasta -o ./results/

# Solubility for individual sequences (comma-separated)
amina run aminosol --sequences "MKTVGQW...,MGSSHHH..." -o ./results/

# ESM2 embeddings
amina run esm2-embedding --fasta ./proteins.fasta -o ./results/
```

---

### Utilities

File preparation and conversion tools.

| Tool | Command | Description |
|------|---------|-------------|
| PDB Cleaner | `amina run pdb-cleaner` | Clean and prepare PDB files |
| PDB to FASTA | `amina run pdb-to-fasta` | Extract sequences from structures |
| PDB Quality Assessment | `amina run pdb-quality-assessment` | Ramachandran and geometry analysis |
| PDB Distance Calculator | `amina run pdb-distance-calculator` | Calculate inter-residue distances |
| PDB Chain Selector | `amina run pdb-chain-select` | Extract or remove specific chains |
| PDB B-factor Overwrite | `amina run pdb-bfactor-overwrite` | Replace B-factors with custom scores |
| Active Site Verifier | `amina run activesite-verifier` | Verify active-site residue presence |
| Protein Relaxer | `amina run protein-relaxer` | Energy minimization for steric clashes |
| MAXIT Converter | `amina run maxit-convert` | Convert between PDB and mmCIF |
| Open Babel Converter | `amina run obabel-convert` | Multi-format molecule conversion |
| Molecule Size Calculator | `amina run mol-size-calculator` | Calculate molecule dimensions |

**Examples:**

```bash
# Clean PDB file
amina run pdb-cleaner --pdb ./messy.pdb -o ./results/

# Clean PDB preserving B-factors
amina run pdb-cleaner --pdb ./messy.pdb --preserve-bfactors -o ./results/

# Extract FASTA from PDB
amina run pdb-to-fasta --pdb ./structure.pdb -o ./results/

# Keep specific chains
amina run pdb-chain-select --pdb ./complex.pdb --chains "A,B" -o ./results/

# Remove chains (invert selection)
amina run pdb-chain-select --pdb ./complex.pdb --chains "C" --invert -o ./results/

# Calculate distance between residues
amina run pdb-distance-calculator --pdb ./protein.pdb --chain1 A --resnum1 50 --chain2 A --resnum2 100 -o ./results/

# Convert PDB to mmCIF
amina run maxit-convert --input ./structure.pdb --format cif -o ./results/

# Relax structure (energy minimize)
amina run protein-relaxer --pdb ./clashing.pdb -o ./results/ --background

# Convert molecule formats
amina run obabel-convert --input ./molecule.mol2 --output-format sdf -o ./results/
```

---

## Output Files

Results are downloaded to your specified output directory. File names include the tool name and job ID:

```
./results/
├── esmfold_abc123_structure.pdb
├── esmfold_abc123_plddt_scores.csv
└── esmfold_abc123_plddt_plot.png
```

---

## Common Options

Most tools support these options:

| Option | Description |
|--------|-------------|
| `-o, --output` | Output directory (required) |
| `-j, --job-name` | Custom name for the job |
| `-b, --background` | Submit job and return immediately |
| `--help` | Show tool parameters and usage |

---

## Links

- [Website](https://aminoanalytica.com)
- [Documentation](https://docs.aminoanalytica.com)
- [Get API Key](https://app.aminoanalytica.com/settings/api)

## License

Apache 2.0