Documentation: https://shellsmith.pages.dev

Shellsmith is a Python SDK and CLI for managing Asset Administration Shells (AAS), Submodels, and Submodel Elements via the Eclipse BaSyx REST API.

It provides full client-side access to AAS resources with a clean Python interface and a powerful typer-based CLI — ideal for scripting, automation, and digital twin integration workflows.

Features

• 🐍 Python SDK for full CRUD access to Shells, Submodels, and Submodel Elements
• ⚡ CLI tool powered by Typer for fast scripting and automation
• ⚙️ Simple .env-based configuration for flexible environment switching
• 🔁 Seamless integration with the Eclipse BaSyx Environment REST API

🚀 Installation

pip install shellsmith

Requires: Python 3.10+

🧠 CLI Usage

Shellsmith provides a powerful command-line interface:

aas --help

Command	Description
info	Display the current Shell tree and identify issues.
upload	Upload a single AAS file or all AAS files from a folder.
nuke	☢️ Delete all Shells and Submodels (irrevocable).
encode	Encode a value (e.g. Shell ID) to Base64.
decode	Decode a Base64-encoded value.
get	Get Shells, Submodels, and Submodel Elements.
delete	Delete Shells, Submodels, or Submodel Elements.
update	Update Shells, Submodels, or Submodel Elements.
create	Create new Shells, Submodels, or Submodel Elements.

ℹ️ Run aas <command> --help to view subcommands and options.

➡️ Full CLI reference: shellsmith.pages.dev/cli

🐍 Python API Usage

You can also use shellsmith as a Python client library to interact with the BaSyx Environment REST API.

import shellsmith

# Fetch all AAS Shells
shells = shellsmith.get_shells()

# Fetch a specific Submodel
submodel = shellsmith.get_submodel("https://example.com/submodels/my-submodel")

# Read and update a Submodel Element's value
value = shellsmith.get_submodel_element_value(submodel["id"], "temperature")
shellsmith.patch_submodel_element_value(submodel["id"], "temperature", "42.0")

ℹ️ shell_id and submodel_id are automatically base64-encoded unless you pass encode=False.

➡️ Full Python API reference: shellsmith.pages.dev/api

🔧 Configuration

The default AAS environment host is:

http://localhost:8081

You can override it in several ways:

• Set the environment variable:

  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234

• Create a .env file in your project with:

  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234

• Use the --host option with any CLI command:

  aas get shells --host https://your-host:1234

• Pass the host parameter in any shellsmith Python function:

  shellsmith.get_shells(host="https://your-host:1234")

💡 The --host CLI flag and host= Python argument take precedence over environment variables and .env.

🤝 Contributing

We welcome contributions!

See the Contributing Guide for setup, testing, and coding standards.

Resources

• https://github.com/eclipse-basyx/basyx-java-server-sdk
• https://github.com/admin-shell-io/aas-specs-api
• https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection