Command Line

Use the txtx Command Line Interface (CLI) to create and execute Runbooks.

Initialize a Runbook

The txtx new command can be used to create a new Runbook and manifest. Simply follow the CLI prompts to get started. Here is an example output:

> txtx new
Enter the name of this workspace: My Project
✔ Choose a Runbook type: · Maintenance: update settings, authorize new contracts, etc.
✔ Enter a name for the runbook (e.g., 'BNS Multisig') · My Runbook
? Enter the description for the runbook (optional) › My runbook helps with my on-chain deployments and
✔ Enter the description for the runbook (optional) · My runbook helps with my on-chain deployments and operations
Created manifest txtx.yml
Created directory runbooks
Created file runbooks/README.md
Created directory runbooks/maintenance
Created runbook runbooks/maintenance/my-runbook.tx

This is an example txtx.yaml file:

---
name: My Project
id: my-project
runbooks:
  - name: My Runbook
    id: my-runbook
    description: My runbook helps with my on-chain deployments and operations
    location: runbooks/maintenance/my-runbook.tx
environments:
  devnet:
    stacks_network_id: devnet
    stacks_api_url: http://localhost:3999
    stacks_operator_address: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC
  testnet:
    stacks_network_id: testnet
    stacks_api_url: https://api.testnet.hiro.so
    stacks_operator_address: ST2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1HR05NNC
  mainnet:
    stacks_network_id: mainnet
    stacks_api_url: https://api.hiro.so
    stacks_operator_address: SP2JHG361ZXG51QTKY2NQCVBPPRRE2KZB1J5QKA2F

List Runbooks

The txtx ls command can be used to list all Runbooks indexed by a manifest:

> txtx ls
ID            Name          Description
my-runbook    My Runbook    My runbook helps with my on-chain deployments and operations

Execute a Runbook

Use the txtx run command to execute a Runbook:

txtx run my-runbook.tx

This example directly executes a Runbook called my-runbook.tx. Runbooks can also be grouped together, given descriptions, and supplied environment variables by creating a txtx manifest. Use the txtx new command to create a manifest. To execute a Runbook that is declared in a manifest, navigate to the manifest directory and run:

txtx run my-runbook

Unsupervised Mode

By default, the txtx run command spins up a web server that can be used to manually interact with your Runbook execution steps. Each step can be validated, and some runtime data can be input, providing flexibility and confidence during execution. We call this supervised execution, because user supervision is required. Here is an example output when running in supervised mode.

→ Processing manifest './txtx.yaml'
✓ Runbook 'My Runbook' successfully checked and loaded

→ Running Web console
http://127.0.0.1:8488

A Runbook can also be run in unsupervised mode, meaning that each of the Runbook steps will be executed automatically, in order. This can be powerful for quick feedback on your on-chain operations. To execute a Runbook in unsupervised mode, use the --unsupervised (or -u) flag:

txtx run my-runbook -u

Here is an example output:

→ Processing manifest './txtx.yml'
✓ Runbook 'My Runbook' successfully checked and loaded

→ Starting runbook 'My Runbook' execution in unsupervised mode
┌───────┬───┐
│ ouput │ 1 │
└───────┴───┘

Was this page helpful?