Get started

Use the Azulene Studio CLI or Python SDK to discover tools, submit a calculation, and retrieve its results. Both are included in the same package and use the same login.

Install

python -m pip install --upgrade azulene-studio
azulene --version

This installs or updates the azulene command line tool and the Python package (imported as azulene). The examples below match version 0.5.18. If you prefer something shorter to type, azu runs the same commands. You can also use python -m azulene.main in place of azulene.

If you previously installed azulene-opal, install azulene-studio with the command above. The older opal command and import opal remain deprecated compatibility aliases; use azulene in new scripts.

Log in

azulene login

Choose email and password or Google when prompted. To open Google sign-in directly, run azulene login --google. If your Studio account has two-factor authentication enabled, follow the verification prompt.

Your session is saved locally and shared with the Python SDK. Run azulene login again if your session can no longer be refreshed. To check the signed-in account and backend, run:

azulene whoami

You need an approved Studio account, access to the tool you want to run, and sufficient credits to submit a job.

Find a tool

azulene jobs get-job-types            # available tool IDs and display names
azulene jobs get-job-types --verbose  # input schemas and featured examples

These commands read the backend catalog for your account. Use the tool ID in commands and Python calls, even when the display name changes. For example, Protein-Ligand Scoring uses opal_ml_score, Protein-Ligand Pose Refinement uses opal_ml_optimize, and Cofactor & Ligand Docking uses sequential_docking.

Run an example

Curated examples supply the inputs and settings for a complete job. Start by listing the examples available to your account:

From the command line:

azulene examples show
azulene examples show absolute_binding --verbose

The verbose view includes runtime and credit estimates. To inspect the HIF-2α example’s files and settings first, download them:

azulene examples download absolute_binding hif2a-belzutifan --dir ./hif2a-example

This writes the input files and input_data.json into hif2a-example without submitting a job. To run the original curated example:

azulene examples submit absolute_binding hif2a-belzutifan

examples submit downloads the curated inputs again and immediately submits a job that uses credits. It does not use edits to your downloaded copy. To submit an edited input_data.json, use this Bash or zsh command:

azulene jobs submit --job-type absolute_binding \
  --input-data "$(cat ./hif2a-example/input_data.json)"

Save the returned job_id to check progress and retrieve results. The HIF-2α ABFE example uses short demonstration settings; its result is not a converged binding free energy.

From Python:

from azulene import examples

print(examples.show("absolute_binding"))
submission = examples.submit("absolute_binding", example_id="hif2a-belzutifan")
if not submission["ok"]:
    raise RuntimeError(submission.get("error"))
job_id = submission["data"]["job_id"]
print(job_id)

Run with your own data

When you are ready, submit your own protein and ligand instead of an example. For ABFE, provide a protein PDB and a ligand structure positioned in its binding site, with a matching ligand SMILES. Replace the paths and SMILES below with your own inputs. The CLI and SDK upload local files automatically.

From the command line:

azulene jobs submit --job-type absolute_binding \
  --input-data '{"pdb_file": "/path/to/your/protein.pdb", "ligand_file": "/path/to/your/bound-ligand.sdf", "ligand_smiles": "CC(=O)Oc1ccccc1C(=O)O", "ph": 7.0}'

From Python:

from azulene import jobs

submission = jobs.submit(
    job_type="absolute_binding",
    input_data={
        "pdb_file": "/path/to/your/protein.pdb",
        "ligand_file": "/path/to/your/bound-ligand.sdf",
        "ligand_smiles": "CC(=O)Oc1ccccc1C(=O)O",
        "ph": 7.0,
    },
)
print(submission)

Each tool page lists the exact inputs that tool expects. See Absolute Binding Free Energy (ABFE) for a full example.

Track your jobs

azulene jobs get-jobs                       # your five most recent jobs
azulene jobs get --job-id YOUR_JOB_ID        # details and current status
azulene jobs wait --job-id YOUR_JOB_ID       # wait for a terminal status

Replace YOUR_JOB_ID with the ID returned by submission. To request cancellation of an active job, run azulene jobs cancel --job-id YOUR_JOB_ID.

Retrieve results

Once the job has completed:

azulene jobs get-result --job-id YOUR_JOB_ID
azulene jobs download --job-id YOUR_JOB_ID

get-result prints the result data. download saves the available result files in the current directory and prints their location. The format depends on the tool; some tools return only structured result data.

From Python, using the job_id saved above:

from azulene import jobs

result = jobs.wait(job_id=job_id)
if not result.get("ok") or result.get("status") != "completed":
    raise RuntimeError(result)
print(result["results"])
print(jobs.download(job_id=job_id))

Check the backend

Production is the default. To see which backend your CLI is using:

azulene config env

If you also have a development account, use azulene config env devel to select it and log in there. Use azulene config env prod to return to production. Each backend has its own login session, jobs, and credits. The selection applies to subsequent CLI commands; restart a Python session after switching backends.

An AZULENE_ENV environment variable overrides the saved selection. Custom AZULENE_SUPABASE_URL and AZULENE_SUPABASE_ANON_KEY settings override both and must be supplied together. Set environment variables before importing azulene in Python.

Run azulene --help, azulene jobs --help, or azulene examples --help to explore the available commands.

Questions

If you have questions or run into a problem, contact the Azulene team at support@azulenelabs.com. We are happy to help.