<!-- markdownlint-disable MD033 MD041 -->
[](https://github.com/astral-sh/ruff)
[](https://pypi.org/project/cardonnay/)
# Cardonnay
<p align="center">
<img src="https://github.com/user-attachments/assets/c0c6b4ef-c647-4e77-952f-1ca9f4beaeec" alt="Cardonnay logo" width="200"/>
</p>
**Cardonnay** is a command-line tool for setting up and managing local Cardano testnets.<br />
It supports multiple preconfigured testnet types and makes it easy to inspect and control their lifecycle.
---
## đ Getting Started
### 1. Create a `conway_fast` testnet
```sh
$ cardonnay create -t conway_fast
Starting the testnet cluster with `/var/tmp/cardonnay/cluster0_conway_fast/start-cluster`:
[...]
Cluster started đ
```
> âšī¸ **Pro Tip:** Add `-b` to create the testnet in the background, or `-c "comment"` to add a comment.
### 2. List running testnet instances
`$ cardonnay control ls`
```json
[
{
"instance": 0,
"type": "conway_fast",
"state": "started",
"comment": null
}
]
```
### 3. Inspect the testnet faucet
`$ cardonnay inspect faucet -i 0`
```json
{
"address": "addr_test1vpgm9cj9u3k63642vju9jqgeqy393upttt0qtwptlesy08gx620qd",
"vkey_file": "/var/tmp/cardonnay/state-cluster0/shelley/genesis-utxo.vkey",
"skey_file": "/var/tmp/cardonnay/state-cluster0/shelley/genesis-utxo.skey"
}
```
### 4. Work with the testnet
```sh
source <(cardonnay control print-env -i 0)
cardano-cli query tip --testnet-magic 42
```
### 5. Stop all running testnet instances
```sh
$ cardonnay control stop-all
Stopping the testnet cluster with `/var/tmp/cardonnay/state-cluster0/stop-cluster`:
[...]
Cluster terminated!
```
## đ ī¸ Installation
### Option 1: Using Nix
If you use [Nix](https://nixos.org/), you can spin up a development shell with all dependencies:
```sh
nix develop
```
This will provide a fully set-up environment, including Python, Cardano binaries, and `jq`.
> âšī¸ **NOTE:** To use the latest `master` branch of `cardano-node`, run
```sh
nix flake update --accept-flake-config --override-input cardano-node github:IntersectMBO/cardano-node/master
nix develop --accept-flake-config
```
---
### Option 2: Using `pip`
Ensure the following dependencies are installed and available in your `PATH`:
- `python3`
- `jq`
- `cardano-node`
- `cardano-cli`
- optional: `cardano-submit-api`
Then install **Cardonnay** in a virtual environment:
```sh
# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install Cardonnay
pip install -U --require-virtualenv cardonnay
# (Optional) Enable shell completions for Bash
source completions/cardonnay.bash-completion
```
Raw data
{
"_id": null,
"home_page": null,
"name": "cardonnay",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cardano, cardano-node, cardano-cli",
"author": null,
"author_email": "Martin Kourim <martin.kourim@iohk.io>",
"download_url": "https://files.pythonhosted.org/packages/c8/2f/5a32161395a0f54b8051832e7328ddb7ed81ae22388976791064603259d4/cardonnay-0.2.1.tar.gz",
"platform": null,
"description": "<!-- markdownlint-disable MD033 MD041 -->\n[](https://github.com/astral-sh/ruff)\n[](https://pypi.org/project/cardonnay/)\n\n# Cardonnay\n\n<p align=\"center\">\n <img src=\"https://github.com/user-attachments/assets/c0c6b4ef-c647-4e77-952f-1ca9f4beaeec\" alt=\"Cardonnay logo\" width=\"200\"/>\n</p>\n\n**Cardonnay** is a command-line tool for setting up and managing local Cardano testnets.<br />\nIt supports multiple preconfigured testnet types and makes it easy to inspect and control their lifecycle.\n\n---\n\n## \ud83d\ude80 Getting Started\n\n### 1. Create a `conway_fast` testnet\n\n```sh\n$ cardonnay create -t conway_fast\nStarting the testnet cluster with `/var/tmp/cardonnay/cluster0_conway_fast/start-cluster`:\n[...]\nCluster started \ud83d\ude80\n```\n\n> \u2139\ufe0f **Pro Tip:** Add `-b` to create the testnet in the background, or `-c \"comment\"` to add a comment.\n\n### 2. List running testnet instances\n\n`$ cardonnay control ls`\n\n```json\n[\n {\n \"instance\": 0,\n \"type\": \"conway_fast\",\n \"state\": \"started\",\n \"comment\": null\n }\n]\n```\n\n### 3. Inspect the testnet faucet\n\n`$ cardonnay inspect faucet -i 0`\n\n```json\n{\n \"address\": \"addr_test1vpgm9cj9u3k63642vju9jqgeqy393upttt0qtwptlesy08gx620qd\",\n \"vkey_file\": \"/var/tmp/cardonnay/state-cluster0/shelley/genesis-utxo.vkey\",\n \"skey_file\": \"/var/tmp/cardonnay/state-cluster0/shelley/genesis-utxo.skey\"\n}\n```\n\n### 4. Work with the testnet\n\n```sh\nsource <(cardonnay control print-env -i 0)\ncardano-cli query tip --testnet-magic 42\n```\n\n### 5. Stop all running testnet instances\n\n```sh\n$ cardonnay control stop-all\nStopping the testnet cluster with `/var/tmp/cardonnay/state-cluster0/stop-cluster`:\n[...]\nCluster terminated!\n```\n\n## \ud83d\udee0\ufe0f Installation\n\n### Option 1: Using Nix\n\nIf you use [Nix](https://nixos.org/), you can spin up a development shell with all dependencies:\n\n```sh\nnix develop\n```\n\nThis will provide a fully set-up environment, including Python, Cardano binaries, and `jq`.\n\n> \u2139\ufe0f **NOTE:** To use the latest `master` branch of `cardano-node`, run\n\n ```sh\n nix flake update --accept-flake-config --override-input cardano-node github:IntersectMBO/cardano-node/master\n nix develop --accept-flake-config\n ```\n\n---\n\n### Option 2: Using `pip`\n\nEnsure the following dependencies are installed and available in your `PATH`:\n\n- `python3`\n- `jq`\n- `cardano-node`\n- `cardano-cli`\n- optional: `cardano-submit-api`\n\nThen install **Cardonnay** in a virtual environment:\n\n```sh\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install Cardonnay\npip install -U --require-virtualenv cardonnay\n\n# (Optional) Enable shell completions for Bash\nsource completions/cardonnay.bash-completion\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Cardano Local Testnet",
"version": "0.2.1",
"project_urls": {
"documentation": "https://github.com/IntersectMBO/cardonnay",
"homepage": "https://github.com/IntersectMBO/cardonnay",
"repository": "https://github.com/IntersectMBO/cardonnay"
},
"split_keywords": [
"cardano",
" cardano-node",
" cardano-cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "103b308f74b72e2d3bc830b0b9daa6a435422266dd24b44fb2419294455cee64",
"md5": "3614b321e6e225b59bdd9478dde83865",
"sha256": "dd8c936473f8d4909a09c3da594abc4e30533b20d3b4c08ccf90eb0155d25803"
},
"downloads": -1,
"filename": "cardonnay-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3614b321e6e225b59bdd9478dde83865",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 75936,
"upload_time": "2025-08-14T17:04:36",
"upload_time_iso_8601": "2025-08-14T17:04:36.733607Z",
"url": "https://files.pythonhosted.org/packages/10/3b/308f74b72e2d3bc830b0b9daa6a435422266dd24b44fb2419294455cee64/cardonnay-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c82f5a32161395a0f54b8051832e7328ddb7ed81ae22388976791064603259d4",
"md5": "33b4ec64e156bc8aaf94b33132efa244",
"sha256": "a076e12fbd1c9532db28f04466a5a702b796ac7ef4834318ee90455e6f8fab9b"
},
"downloads": -1,
"filename": "cardonnay-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "33b4ec64e156bc8aaf94b33132efa244",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 70453,
"upload_time": "2025-08-14T17:04:38",
"upload_time_iso_8601": "2025-08-14T17:04:38.504942Z",
"url": "https://files.pythonhosted.org/packages/c8/2f/5a32161395a0f54b8051832e7328ddb7ed81ae22388976791064603259d4/cardonnay-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 17:04:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IntersectMBO",
"github_project": "cardonnay",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cardonnay"
}
JSON
