Jolly CLI

Jolly is a local robot-arm physics simulator for terminal users and LLM agents. It uses PyBullet in deterministic direct mode and saves state between commands.

Jolly includes two offline robot profiles:

• jolly6: an original six-axis arm with a parallel gripper.
• so101: a lightweight five-axis SO-101 simulation profile with a gripper.

The package also accepts scenes, challenges, an engine benchmark, a native PyBullet viewer, and an optional local web viewer. No cloud service, MCP server, API key, or network connection is required at runtime.

See Jolly in action

Local web simulator

Watch the WebM recording

Terminal-native control

Watch the MP4 recording

Install

Install the command from PyPI with Python 3.10 or later:

python -m pip install jolly-cli
jolly state --json

For Python development, create a virtual environment on Python 3.10 or later:

python -m venv .venv
. .venv/bin/activate
pip install -e '.[web,dev]'

PyBullet publishes limited binary wheels. On platforms without a matching wheel, use conda-forge or install a C++ build toolchain for the source build.

Install the local LLM skill with the Skills CLI:

npx skills add ./skills/jolly

Quick start

jolly models --json
jolly reset --model jolly6 --scene blocks --json
jolly state --json
jolly move --joints "0,-25,70,-45,0,0" --gripper 0.0 --json
jolly reach --x 0.30 --y 0.10 --z 0.18 --gripper 0.0 --json
jolly render
jolly challenge list --json
jolly benchmark --json

Start the optional local web viewer:

jolly serve --host 127.0.0.1 --port 8765

Open http://127.0.0.1:8765. The JSON API documentation is at http://127.0.0.1:8765/api/docs.

Open the native PyBullet window on a machine with a display:

jolly viewer --model jolly6 --scene blocks

Command contract

All motion uses meters and degrees. Gripper 0.0 means open. Gripper 1.0 means closed. Mutating commands save state under the operating system state directory. Set JOLLY_STATE_DIR to isolate or relocate state.

Important commands:

Jolly rejects joint-limit violations and unsafe workspace targets. By default, Jolly rolls back a motion that creates a collision. Use --allow-collision only for controlled collision tests.

Architecture

jolly-cli/
├── pyproject.toml
├── README.md
├── SKILL.md
├── LICENSE-MIT
├── LICENSE-APACHE
├── THIRD_PARTY_LICENSES.md
├── jolly/
│   ├── cli.py
│   ├── benchmark.py
│   ├── challenges.py
│   ├── assets/
│   │   ├── jolly6.urdf
│   │   └── so101.urdf
│   ├── core/
│   │   ├── physics.py
│   │   ├── models.py
│   │   ├── scenes.py
│   │   └── store.py
│   └── web/
│       ├── app.py
│       └── index.html
├── skills/jolly/SKILL.md
└── tests/

Physics scope

PyBullet performs rigid-body simulation, FK, IK, contact generation, and scene settling. Jolly uses deterministic state restoration across short CLI processes. The grasp helper attaches a nearby graspable object while the gripper is closed. This helper makes terminal pick-and-place repeatable. It is not a soft-contact or motor-current model.

The bundled SO-101 profile uses original primitive collision geometry. Its joint layout and limits derive from Apache-2.0 upstream robot metadata. It does not include the upstream CAD meshes and does not claim visual hardware fidelity.

License

Jolly source code and original assets are available under your choice of the MIT License or Apache License 2.0. See LICENSE-MIT and LICENSE-APACHE. Third-party details appear in THIRD_PARTY_LICENSES.md.