cli

Astria Go CLI

The astria-go CLI simplifies local rollup development and minimizes dependencies. It provides functionality to easily run the Astria stack and interact with the Sequencer.

Table of Contents

• Installation
• Running the Astria Sequencer
• Instances
• Configuration
• Development

Installation

See all releases here.

Install From GitHub Release

1. Download the latest release for your platform:

   # For macOS silicon (arm64)
   export RELEASE_URL="https://github.com/astriaorg/astria-cli-go/releases/download/v0.12.0/astria-go-v0.12.0-darwin-arm64.tar.gz"
   curl -L $RELEASE_URL --output astria-go.tar.gz

2. Extract the binary:

   tar -xzvf astria-go.tar.gz

3. Verify the installation:

   ./astria-go version

4. Optionally, move the binary to a location in your PATH:

   mv astria-go /usr/local/bin/

Install Nightly Release

1. Download the nightly release:

   export NIGHTLY_URL="download url of the build you need"
   curl -L $NIGHTLY_URL > astria-cli.tar.gz

2. Extract and install:

   tar -xvzf astria-cli.tar.gz
   mv astria-go /usr/local/bin/

3. Verify the installation:

   astria-go version

Build Locally from Source

Prerequisites:

• GO
• just

Steps:

1. Clone the repository:

   git clone git@github.com:astriaorg/astria-cli-go.git
   cd astria-cli-go

2. Build the project:

   just build

3. Verify the build:

   just run "version"
   # or
   go run main.go version

Running the Astria Sequencer

Initialize Configuration

astria-go dev init

This command downloads binaries, generates configuration files, and initializes CometBFT. Files are organized in the ~/.astria/<instance> directory.

Usage

Run a Local Sequencer

astria-go dev run --network local

This command starts a local Sequencer (Cometbft and Astria-Sequencer), Conductor, and Composer using pre-built binaries.

Run Against a Remote Sequencer

To run Composer and Conductor locally against a remote Astria Sequencer:

# Run against the Astria Dusk dev net 
astria-go dev run --network dusk

When using a remote sequencer, you'll need to create an account on the remote sequencer. For more details, refer to the Astria documentation.

Run Custom Binaries

You can run components from a local monorepo during development. For example, to use a locally compiled Conductor:

astria-go dev run --network local \
  --conductor-path <absolute path to the Astria mono repo>/target/debug/astria-conductor

Or update the local path in the ~/.astria/<instance>/networks-config.toml:

[networks.local.services.conductor]
name = 'astria-conductor'
version = 'dev'
download_url = ''
local_path = 'path to your local conductor'
args = []

You can swap out some or all binaries:

astria-go dev run --network local \
  --sequencer-path <sequencer bin path> \
  --cometbft-path <cometbft bin path> \
  --composer-path <composer bin path> \
  --conductor-path <conductor bin path>

Interact with the Sequencer

Use astria-go sequencer [command] to interact with the sequencer. For a full list of commands:

astria-go sequencer -h

Use the --network flag to configure which sequencer network the commands will run against.

Instances

Use the --instance flag to manage multiple rollups:

astria-go dev init
astria-go dev init --instance hello
astria-go dev init --instance world

This creates separate directories in ~/.astria/ for each instance, containing configs and binaries for running the Astria stack.

Configuration

The CLI uses the following configuration files:

1. tui-config.toml: Controls app start state of the devrunner TUI
2. base-config.toml: Sets service environment variables
3. networks-config.toml: Configures services and sequencer networks
4. sequencer-networks-config.toml: Used for astria-go sequencer commands

Set TUI App Start State

Once astria-go dev init has been run, edit ~/.astria/tui-config.toml to control the starting settings of the TUI app.

The highlight_color and border_color accept both W3C named colors and hexadecimal notation:

highlight_color = "deepskyblue" # names should be all lowercase with no spaces
border_color = "#808080"

Set Service Environment Variables

Edit ~/.astria/<instance>/config/base-config.toml to add or change settings:

lower_snake_case_var_name = 'value'

Configure Networks and Services

The ~/.astria/<instance>/networks-config.toml file configures which services are run and provides overrides for different sequencer networks.

Customizing Service Versions

To use a specific version of a service, update the version, download_url, and local_path in the networks-config.toml. For example, to roll back Composer:

[networks.local.services.composer]
name = 'astria-composer'
version = 'v0.7.0'
download_url = 'https://github.com/astriaorg/astria/releases/download/composer-v0.7.0/astria-composer-aarch64-apple-darwin.tar.gz'
local_path = '<your home directory>/.astria/default/bin/astria-composer-v0.7.0'
args = []

Then run astria-go dev init to download the specified service.

For local development, point to your locally built binary:

[networks.local.services.composer]
name = 'astria-composer'
version = 'dev'
download_url = ''
local_path = '<path to your local binary>'
args = []

Run a Generic Service

Add a local service to your network:

[networks.local.services.echo]
name = 'echo'
version = ''
download_url = ''
local_path = '/bin/bash'
args = ['-c', 'echo -e "hello world\nhello again!"']

NOTE: All arguments are interpreted literally. This may affect how some service arguments are parsed. Running through a bash shell command resolves this issue in the case of running an echo command above.

Add a service from a release:

[networks.local.services.your_service]
name = 'your_service'
version = 'v0.0.0'
download_url = 'download url to the release'
local_path = '<your home directory>/.astria/default/bin/<your_service_name-version>'
args = ['your', 'service', 'args']

Adding a New Network

To add a new network, append a new section to networks-config.toml:

[networks.sequencer_only]
sequencer_chain_id = 'sequencer-only'
sequencer_grpc = 'http://127.0.0.1:8080'
sequencer_rpc = 'http://127.0.0.1:26657'
rollup_name = 'astria-test-chain'
default_denom = 'nria'

[networks.sequencer_only.services]
[networks.sequencer_only.services.cometbft]
name = 'cometbft'
version = 'v0.38.8'
download_url = 'https://github.com/cometbft/cometbft/releases/download/v0.38.8/cometbft_0.38.8_darwin_arm64.tar.gz'
local_path = '<your home directory>/.astria/default/bin/cometbft-v0.38.8'
args = []

[networks.sequencer_only.services.sequencer]
name = 'astria-sequencer'
version = 'v0.15.0'
download_url = 'https://github.com/astriaorg/astria/releases/download/sequencer-v0.15.0/astria-sequencer-aarch64-apple-darwin.tar.gz'
local_path = '<your home directory>/.astria/default/bin/astria-sequencer-v0.15.0'
args = []

Run your new network with:

astria-go dev init
astria-go dev run --network sequencer_only

Interact with Sequencer Networks

The ~/.astria/sequencer-networks-config.toml provides presets for interacting with different sequencer networks when using astria-go sequencer commands. Use the --network <network name> flag to simplify your commands.

To add presets for a new network, append to sequencer-networks-config.toml:

[networks.new_network]
sequencer_chain_id = 'new-network'
sequencer_url = '<rpc endpoint for the sequencer>'
asset = '<new asset>'
fee_asset = '<new fee asset>'

Use the new config with:

astria-go sequencer nonce <other args> --network new_network

Development

Requirements:

• Go version 1.22 or newer
• Updated gopls settings for correct parsing of build tags

The CLI uses Cobra for structuring the command-line interface. To add new commands:

1. Install Cobra CLI:

   go install github.com/spf13/cobra-cli@latest

2. Add a new command:

   cobra-cli add <command-name>

TUI Logs

TUI logs are written to ~/.astria/<instance>/astria-go.log. This file is overwritten each time you run the TUI.

Testing

Unit Tests

# Run unit tests
just test

Integration Tests

The integration tests require a running local sequencer network to test against. Prior to testing, run:

just run dev run --network local

In a new terminal window run:

# Run integration tests
just test-integration

# Run all tests
just test-all