dicehub Python

The dicehub Python SDK and CLI let you manage simulations on dicehub. The project is available under the MIT license.

Install

dicehub supports CPython 3.10 through 3.14.

pip install dicehub-python

The package provides the dicehub Python module and the dicehub command.

Get started

Create a dicehub account, then create an API key. A key with VIEW_PROJECT_INFO can list your projects. Set the key in DICEHUB_API_KEY and run:

import os

import dicehub

with dicehub.Client(api_key=os.environ["DICEHUB_API_KEY"]) as client:
    for project in client.projects.list().projects:
        print(project.project_id, project.name)

The client connects to https://dicehub.com by default. Pass base_url when you use another dicehub deployment.

The same API is available through dicehub.AsyncClient. See the async guide.

CLI

The CLI uses DICEHUB_API_KEY and connects to dicehub.com by default.

dicehub auth status
dicehub project list
dicehub run machine-types

Commands return JSON using the dicehub.cli/v1 schema. See the CLI reference for all commands and options.

Supported operations

The SDK covers authentication, API keys, groups, projects, apps, configurations, resources, storage, runs, templates, users, and teams. The documentation lists the available methods and the API-key permissions they need.

The complete feature set requires dicehub server 0.22.9 or newer. Group automation works with server 0.22.1, membership selectors with 0.22.2, and configuration value updates with 0.22.6. GitLab CI tests the platform-independent wheel on Linux. Windows and macOS are not validated yet.

See the authentication guide for session-only operations and the resources and storage guide for current permission and transfer limits. The getting-started guide explains the package-name change for users of the former private dicehub distribution. Release history and deferred features are recorded in the changelog.

Changes and costs

API-key permissions limit what a program can read or change. Starting a run can incur charges. Deleting a resource can also delete its descendants. The SDK sends each mutation once; check the current state before you repeat an operation whose result is unknown.

Examples and development

Start with the authentication example, the controlled cube workflow, or the car mesh workflow.

Development instructions are in CONTRIBUTING.md. See the architecture, and testing guide for development details.