Skip to content

Installation

Requirements

  • Python 3.11 or later
  • A Crucible API at version 4.0 or later; the shell's status bar flags an older server. Upgrading from 3.x? See Upgrading to 4.0.
  • A Crucible account (crucible.lbl.gov); an API key only for scripts, CI, and batch jobs

Install from PyPI

pip install nano-crucible

Optional extras

# Parser support (installs ASE for the built-in LAMMPS parser)
pip install nano-crucible[parsers]

Note: prompt_toolkit (interactive shell) is a core dependency; no extra is needed.

Development install

git clone https://github.com/MolecularFoundryCrucible/nano-crucible.git
cd nano-crucible
pip install -e ".[dev]"

Configuration

Sign in with a browser

crucible login            # opens your browser on this computer
crucible login --device   # over SSH or without a browser: approve a code on any device
crucible login --paste    # sign in in any browser and paste the code it shows
crucible whoami           # shows "Signed in with"
crucible logout

If the browser shows an error after you choose Allow, it cannot reach the terminal: Chrome's local network rules, WSL, and containers can block it. Press Enter while crucible login waits, sign in again, and paste the code the page shows, or start with crucible login --paste. The code works once, within five minutes.

The sign-in is kept in your OS keyring (macOS Keychain, Windows Credential Locker, or Secret Service on Linux). Where no keyring is reachable, such as a headless Linux machine or cluster node, it goes in a file only you can read in the config directory; set auth_store to keyring, file, or memory to choose. Sessions renew themselves and end after 14 days without use or 90 days at most.

Some actions, such as creating an API key, need a sign-in from the last 10 minutes. The CLI asks you to sign in again in your browser when that happens. A sign-in approved with a code (--device) cannot do these actions; use a computer with a browser or the Hub.

An API key still works and is the right choice for scripts, CI, and batch jobs. The CLI uses, in order: an api_key passed to CrucibleClient, CRUCIBLE_API_KEY, your sign-in, then api_key in the config file.

API key: config file

Run the interactive setup wizard once after installing:

crucible config init

It offers to sign you in with this computer's browser and create a key, or takes a key you paste without displaying it, and writes a config file at ~/.config/nano-crucible/config.ini (path varies by OS). All subsequent CLI and Python API calls will use it automatically. If a corresponding environment variable is set, it takes precedence and the wizard reports that override.

You can review or change settings at any time:

crucible config show       # view current settings
crucible config set KEY VALUE
crucible config unset KEY  # remove an override
crucible config edit       # open in your editor

Useful config keys:

Key Description
api_key Your Crucible API key
api_url Optional API override (default: https://crucible.lbl.gov/api/v3)
current_project Current project ID used when a command omits --project-id
hub_url Crucible Hub address (default: https://crucible.lbl.gov/hub)
auth_store Where crucible login keeps tokens: auto (default), keyring, file, or memory

Alternative: pass credentials directly in Python

from crucible import CrucibleClient

client = CrucibleClient(
    api_key="your-api-key",
)

Alternative: environment variables (useful for CI/automation)

export CRUCIBLE_API_KEY="your-api-key"

Set CRUCIBLE_API_URL only when targeting staging or another non-default deployment. Environment variables take priority over the config file when both are present.

Use explicit --project-id arguments for automation. CRUCIBLE_CURRENT_PROJECT was removed in 4.0.0 because it could silently redirect commands to another project; the CLI stops if it is set.

If an older config explicitly selects API v1 or v2, Nano displays a migration warning. Run crucible config unset api_url to inherit the API v3 endpoint packaged with Nano, or set the override to the desired deployment explicitly.


Getting your API key

crucible config init can create one: it signs you in with your browser and saves the new key. You can also create a key on your Hub account page: crucible.lbl.gov/hub/account. After crucible login, crucible account keys create NAME also creates one. A key is shown only once.


Verify your setup

crucible whoami

Or in Python:

client = CrucibleClient()
print(client.whoami())