Getting Started
Zip Setup

Zip Setup

For users who prefer not to use Docker, the ZIP distribution contains Yaci CLI, configuration files, and packaged examples. It allows you to download and manage necessary components like Cardano Node, Yano, Ogmios, Kupo, and Yaci Store directly through the command line.

Overview

The Zip distribution is perfect for:

  • Developers and system administrators: Quickly set up custom node or multi-node networks
  • Users wanting more control: Easily manage compatible component versions and configurations
  • Non-Docker environments: Environments where Docker is not available or preferred

Note: Yaci Viewer is not included in the Zip distribution. To add viewer functionality, you can install Yaci Viewer separately through NPM. See the NPM installation guide for details.

⚠️

PV11-compatible Ogmios/Kupo binaries are currently published only as Linux x86_64 builds. On macOS arm64 native CLI, those specific Ogmios/Kupo defaults cannot run directly. Use Docker as a workaround, or set custom ogmios.url / kupo.url values when compatible native builds are available.

Key Advantages

  • Reduced Disk Space: Requires less disk space than Docker, containing only the Yaci CLI binary and configuration files
  • Version Flexibility: Specify compatible versions of Cardano Node and other components directly in the download configuration
  • Customizable Setup: Selectively enable components like Yaci Store, Ogmios, and Kupo to achieve the same functionality as the Docker distribution

Prerequisites

Supported Platforms

Yaci CLI is currently supported on:

  1. Linux x86: Tested on Ubuntu 22.04 and later
  2. macOS 14 (Arm64) or later
⚠️

Upgrading from a previous version? If you have an existing Yaci CLI installation, remove the $HOME/.yaci-cli folder before installing the new version. This ensures all components are downloaded with their latest compatible versions.

rm -rf $HOME/.yaci-cli

Installation

Step 1: Download and Extract

  1. Download the latest Yaci CLI Zip file from the releases page (opens in a new tab)

    File name format: yaci-cli-<version>-<os>-<arch>.zip

    Examples:

    • Linux: yaci-cli-x.y.z-linux-X64.zip
    • macOS: yaci-cli-x.y.z-macos-ARM64.zip

  2. Unzip the downloaded file

  3. Navigate to the extracted folder where you'll find:

    • yaci-cli - The main executable binary
    • config/ - Configuration files directory
    • examples/ - Runnable examples for Wallet SDK, MeshJS, Evolution SDK, and Sutra Elixir

Step 2: macOS Setup (macOS users only)

On macOS, downloaded executables are quarantined by default. Remove the quarantine:

xattr -d com.apple.quarantine path/to/yaci-cli-distribution/yaci-cli

Replace path/to/yaci-cli-distribution with your actual path.

Getting Started

Step 1: Run Yaci CLI

Navigate to the extracted folder and run:

./yaci-cli

You'll see the Yaci CLI prompt: yaci-cli:>

Step 2: Download Required Components

The ZIP distribution doesn't include the necessary components for creating a devnet. Download them using:

yaci-cli:> download

This downloads the configured components for your platform:

  • Cardano Node
  • Yano
  • Ogmios
  • Kupo
  • Yaci Store

All components are downloaded to $HOME/.yaci-cli by default.

Download Options

Overwrite existing components:

yaci-cli:> download --overwrite

Download individual components:

yaci-cli:> download -c node
yaci-cli:> download -c yano
yaci-cli:> download -c ogmios
yaci-cli:> download -c kupo
yaci-cli:> download -c yaci-store
⚠️

You can change the default Yaci CLI home folder by setting the yaci.cli.home property in the application.properties configuration file.

Step 3: Create Your First Devnet

Once components are downloaded, create and start a devnet:

yaci-cli:> create-node -o --start

This creates a new devnet with a single node and starts it with a 1-second block time.

Note: In the Zip distribution, only the Cardano devnet is started by default. Additional components (Yaci Store, Ogmios, Kupo) are not automatically started. To enable these services:

Option 1: Configure in application.properties before starting (see Configuration section)

Option 2: Enable via CLI commands:

yaci-cli:> enable-yaci-store    # Enable Yaci Store
yaci-cli:> enable-kupomios     # Enable both Ogmios and Kupo

Important: To use Yaci Viewer (the blockchain explorer) with your devnet, you must enable Yaci Store as Yaci Viewer retrieves its data from Yaci Store.

Customize Block Time (Optional)

Default Configuration: The standard create-node command creates a devnet with 1-second block time. You can customize this for faster development cycles.

To create a devnet with custom block time:

# Sub-second block time (200ms)
yaci-cli:> create-node -o --block-time 0.2 --slot-length 0.2 --start
 
# Sub-second block time (100ms) with 80-slot epochs
yaci-cli:> create-node -o --block-time 0.1 --slot-length 0.1 --epoch-length 80 --start
 
# 5-second block time
yaci-cli:> create-node -o --block-time 5 --slot-length 5 --start

Important considerations:

  • For sub-second block times, always set both --block-time and --slot-length
  • The slot length must be equal to or less than the block time
  • --epoch-length defines the number of slots per epoch (default: 600)
  • With 0.1s slots and 80-slot epochs, each epoch lasts 8 seconds

Configuration

The config folder contains three important configuration files:

application.properties

Main configuration file for Yaci CLI functionality.

Enable Optional Components

By default, optional components are disabled. Enable them as needed:

ogmios.enabled=true
kupo.enabled=true
yaci.store.enabled=true

Yaci DevKit v0.12.0-beta5+: Yaci Store uses scalus transaction evaluation by default, so transaction building, script cost evaluation, and transaction submission do not require Ogmios. If Ogmios is enabled and running when Yaci Store starts, DevKit switches Yaci Store to ogmios evaluation mode.

Update Ports

Customize default ports:

ogmios.port=1337
kupo.port=1442
yaci.store.port=8080

node.properties

Contains Cardano Node configuration. Update as needed to modify the node's genesis configuration.

Node Mode

The default node mode is companion.

nodeMode=companion

Use yano-only for a lighter setup where Yano runs as the only node and Yaci Store syncs directly from Yano.

nodeMode=yano-only

See Node Modes for details.

download.properties

Contains default download versions for components. You can:

  • Update versions for specific components
  • Provide direct download URLs
  • Control your environment with specific compatible versions

Basic Usage

Essential Commands

Once your devnet is running, you'll be in the "devnet:default" context:

Fund Test Addresses

devnet:default> topup <address> <ada_amount>

Check UTXOs

devnet:default> utxos <address>

Get Devnet Information

devnet:default> info

Reset Devnet Data

devnet:default> reset

Stop Devnet

devnet:default> stop

Advanced Configuration

Enable Services Before Creating Devnet

yaci-cli:> enable-yaci-store   # Enable Yaci Store
yaci-cli:> enable-kupomios    # Enable both Ogmios and Kupo

Custom Block Times and Epochs

# Custom slots per epoch
yaci-cli:> create-node -o -e 30 --start
 
# Sub-second block times (e.g., 200ms)
yaci-cli:> create-node -o --block-time 200 --start

Service URLs

When enabled, services are available at:

Packaged Examples

The ZIP distribution includes examples under examples/:

  • wallet-demo
  • meshjs-mint-nft
  • evolution-sdk
  • sutra-elixir

See examples/README.md in the distribution for a quick overview.

Multi-Node Networks

Since Yaci CLI is used in both Yaci DevKit and this distribution, the commands to create a multi-node network remain the same. You can follow the instructions provided in the Additional Nodes on Different Machines section of the multi-node setup guide.

Next Steps

Docker SetupNPM Setup