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 inputs 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
Supervised 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
Unsupervised Mode
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 │
└───────┴───┘
Providing Inputs
Runbook inputs can be provided in the CLI by using the --input flag.
Each input is a key/value that can be referenced in the Runbook via input.key.
For example, the following command:
txtx run my-runbook -input key1=value1 -input key2=value2
will provide the input.key1 and input.key2 inputs to the Runbook.