OpenSees CLI Documentation

Command-line interface for authentication and simulation runs.

Install

pip install opensees_cli

The PyPI distribution name matches the import name: import opensees_cli and python -m opensees_cli.

Package page: pypi.org/project/opensees_cli (PyPI may still show opensees-cli in the page title; that is the same project—hyphens and underscores are equivalent there.)

PATH and the ops command

After install, pip places the ops launcher in a scripts directory (e.g. Scripts on Windows, bin on macOS/Linux). That folder might not be on your PATH, so ops may be missing in a new terminal.

• On the first interactive run, the CLI can offer to add that folder to your PATH automatically.
• To always run that step (for example on Windows), use:

python -m opensees_cli set-path

Answer Y when prompted. Open a new terminal afterward, then try ops version.

If ops is still not found, you can run the same program with:

python -m opensees_cli

To see the PATH offer again after you skipped it, delete the marker file ~/.opensees/path_fixed (on Windows: %USERPROFILE%\.opensees\path_fixed) and run python -m opensees_cli or python -m opensees_cli set-path.

Quick Start

# 1) Create account
ops auth signup --email you@example.com

# 2) Confirm account
ops auth confirm --email you@example.com --code 123456

# 3) Log in
ops auth login --email you@example.com

# 4) Submit a simulation
ops run submit ./model.py --timeout 300 --wait

Top-Level Commands

ops set-path
ops version
ops status
ops help

• set-path: interactive prompt to add the ops launcher directory to your PATH (use python -m opensees_cli set-path if ops is not on PATH yet)
• version: print CLI version
• status: show account details, signup time, and usage quota (calls the API)

Auth Commands

ops auth signup --email you@example.com
ops auth confirm --email you@example.com --code 123456
ops auth resend-code --email you@example.com
ops auth login --email you@example.com
ops auth logout
ops auth status
ops auth forgot-password --email you@example.com
ops auth reset-password --email you@example.com --code 123456
ops auth change-password
ops auth help

Run Commands

ops run submit ./model.py --timeout 120
ops run submit ./model.py --wait
ops run status <run_id>
ops run output <run_id>
ops run result <run_id>
ops run cancel <run_id>
ops run list --limit 20
ops run help

run submit options

• file (required positional): local path to a .py file (uploaded if the path exists under its filename), or a cloud path such as model.py or lab/model.py
• --timeout, -t: max wall time per task in seconds (default 120). The API requires your monthly runtime remaining ≥ timeout × number of tasks. Runs above 900s use Fargate when configured; otherwise the 900s Lambda limit applies.
• --wait, -w: wait and stream output until completion (default: return immediately with the analysis ID on stdout; progress on stderr)

Validation enforced by CLI (local uploads):

• path must exist on disk and be a regular file
• file extension must be .py
• upload uses the cloud file API (same as ops files upload; up to 100 MB per file)

Common Workflows

Check account + quota

ops status

Submit and monitor a run later (default)

ops run submit ./model.py
ops run status <run_id>
ops run output <run_id>
ops run result <run_id>

Submit and wait for live output

ops run submit ./model.py --wait

Reset password

ops auth forgot-password --email you@example.com
ops auth reset-password --email you@example.com --code 123456