Skip to content

Command Line Guide

We can now use the command line to create a Cardano wallet and output all the files we will need to manage the wallet. We can also start the API and access the API Swagger documentation.

Bursa can also be used to generate multi-signature scripts, hashes, keys, including keys and certificates needed to run a Cardano stake pool.

There are currently 11 categories of commands that Bursa can run which makes it a power tool for Cardano users.

Bursa Command Categories

  1. wallet   - Commands for generating wallet and the files needed to manage a Cardano wallet
  2. api     - Commands for running API
  3. kes-agent    - Commands for running the KES agent daemon for a Cardano block producer
  4. cert    - Commands for generating various Cardano certificates
  5. hash     - Commands for generating cryptographic hashes used in Cardano
  6. script    - Commands for multi-signature operations
  7. address - Commands for working with Cardano addresses
  8. key     - Commands for deriving individual keys from a mnemonic
  9. tx - Offline transaction operations
  10. sign - CIP-8/CIP-30 message signing and verification
  11. signer - Remote signing service

Use Command Line to Create a Wallet and Output Wallet Files

Section titled “Use Command Line to Create a Wallet and Output Wallet Files”

We can use the command line to create a wallet and output all the files we will need to manage our Cardano wallet.

✅ For this example we create the wallet files to the dev folder by using the --output flag and giving it a directory to output to.

./bursa wallet create --output dev

bursa-wallet-create-with-output-string

Now we will have all the wallet files in our dev directory.

bursa-wallet-files

Restore an existing BIP-39 mnemonic from a protected file, then inspect the generated key files:

Terminal window
./bursa wallet restore --mnemonic-file dev/seed.txt --output restored-wallet
./bursa wallet load --dir restored-wallet

--output writes addresses and key files; without it, restoration logs addresses only. Restoration does not copy the mnemonic into the output directory. Keep mnemonic and signing-key files private and backed up securely. Mnemonic sources are checked in this order: deprecated --mnemonic, MNEMONIC environment variable, --mnemonic-file, then the default seed.txt file. Unset MNEMONIC when using --mnemonic-file. The --mnemonic and --password arguments are deprecated because process arguments are visible to other local users; use --mnemonic-file and --password-file instead. Use --password-file /path/to/password.txt if the wallet was derived with a BIP-39 password; this is a derivation password, not encryption for the output files.

wallet load reads existing key files without deriving a new wallet. Private key hex is hidden by default; --show-secrets explicitly reveals it. Use ./bursa wallet restore --help and ./bursa wallet load --help for the available options.


If we want to use the API we can use the command line to start it, by running the following command.

./bursa api

bursa-start-api

You can check the Bursa API by going to your IP:port/swagger/index.html. Please adjust the IP and your port if needed.

http://localhost:8080/swagger/index.html

bursa-swagger

For non-loopback listeners, use the configuration reference to configure TLS and exactly one bearer authentication trust source.


Start the KES agent daemon for a Cardano block producer with a YAML configuration file:

./bursa kes-agent --config /path/to/kes-agent.yaml

The --config flag selects the YAML configuration file. When the flag is omitted, Bursa uses the BURSA_CONFIG environment variable. Configure the kes_agent.mode value as serve-key or sign. Use the configuration reference for the kes_agent YAML fields and environment variables, including the mode and required socket, key, and timing settings.

Use bursa kes-agent control to send a command to a running local KES agent through its control socket:

./bursa kes-agent control [--config /path/to/kes-agent.yaml] [--socket /run/bursa/kes-agent-control.sock] [--profile PROFILE] <command>

An explicit --socket value takes precedence. Without --socket, the command reads kes_agent.control_socket from the YAML file selected by --config; when --config is omitted, BURSA_CONFIG selects that file. The command does not discover a control socket from another source. See the configuration reference for kes_agent.control_socket, socket permissions, and configuration-file selection.

Use --profile to select the profile affected when the agent serves several profiles. Without --profile, info lists every profile; a single-profile agent can omit the profile name.

The control command provides these subcommands:

  • info prints the agent state. It does not require additional flags.
  • gen-staged-key [--out FILE] generates a staged key. The optional --out flag writes the KES verification key as a cardano-cli envelope, prints the JSON reply before attempting the write, and refuses to overwrite an existing file.
  • install-key --opcert FILE installs a staged key from a NodeOperationalCertificate cardano-cli envelope. The command requires the --opcert flag.
  • drop-key --target VALUE drops key material. The --target flag is required and accepts only staged, active, or all.

The command prints agent replies as JSON and represents byte fields as hexadecimal. An agent refusal causes a non-zero CLI exit. Each control request has a 30-second limit, and cancellation ends blocked socket I/O promptly.

Rotate a KES key in three steps:

  1. Generate the staged key and write its verification key to an envelope:

    ./bursa kes-agent control --config /etc/bursa/kes-agent/config.yaml gen-staged-key --out kes.vkey
  2. Issue an operational certificate for kes.vkey offline with the pool cold key. The agent does not issue the certificate.

  3. Install the certificate and inspect the result:

    ./bursa kes-agent control --config /etc/bursa/kes-agent/config.yaml install-key --opcert node.cert
    ./bursa kes-agent control --config /etc/bursa/kes-agent/config.yaml info

The tx commands inspect and sign an existing transaction without contacting a node. Supply unsigned.tx as hex CBOR or a JSON text envelope containing cborHex:

Terminal window
./bursa tx decode --tx-file unsigned.tx
./bursa tx id --tx-file unsigned.tx
./bursa tx sign --tx-file unsigned.tx \
--signing-key-file dev/payment.skey --era Conway --out-file signed.tx

Repeat --signing-key-file to add multiple signers. The optional --era flag accepts Shelley, Allegra, Mary, Alonzo, Babbage, Conway, or Dijkstra without regard to letter case. Use it with tx sign, tx witness, or tx assemble when raw CBOR or a legacy era-less Tx envelope does not identify a single era:

Terminal window
./bursa tx witness --tx-file unsigned.tx \
--signing-key-file dev/payment.skey --era Conway --out-file payment.witness
./bursa tx assemble --tx-file unsigned.tx \
--witness-file payment.witness --era Conway --out-file assembled.tx

Repeat --witness-file to include additional witnesses. Bursa uses an era named in a text envelope and requires it to match --era when both are present. Raw hex and a legacy era-less Tx envelope work without --era only when the CBOR resolves to one era. If the CBOR is valid in more than one era, Bursa does not guess: provide --era or an era-typed envelope such as Tx ConwayEra. An unknown era or a conflict between the envelope and --era fails.

Signing and assembly write JSON text envelopes to --out-file, or to standard output when it is omitted. Signed and assembled outputs use TxSignedShelley for Shelley, Tx <Era>Era for Allegra through Dijkstra, such as Tx ConwayEra, and plain Tx for Byron. Detached witnesses use TxWitness <Era>Era for Shelley through Dijkstra, such as TxWitness ConwayEra, and plain TxWitness for Byron.

The /api/tx/sign and /api/tx/assemble endpoints resolve the era from tx_cbor. When raw or era-less CBOR is valid in multiple eras, the request returns HTTP 400 unless tx_cbor uses an era-named text envelope such as Tx ConwayEra; the response includes remediation guidance. tx decode --protocol-params protocol-parameters.json also estimates the minimum fee from a Cardano protocol-parameters JSON file. Use ./bursa tx --help and each subcommand’s --help for options.

The --era option is available on tx sign, tx witness, and tx assemble. For raw or era-less CBOR that is valid in more than one era, --era is required; for example:

Terminal window
./bursa tx sign --tx-file unsigned.tx --era conway \
--signing-key-file dev/payment.skey --out-file signed.tx

Bursa resolves the era from an era-typed JSON text envelope, such as one with type Tx ConwayEra, when the flag is absent. Without --era, Bursa accepts raw or era-less CBOR only when it decodes unambiguously. Provide --era or an era-typed envelope when the input is ambiguous. The command fails when --era conflicts with the era declared by the input envelope.

The resolved era selects the output envelope type and witness encoding for signing, witnessing, and assembly.

sign data produces a CIP-8/CIP-30 COSE signature and public key as JSON. Set ADDRESS_HEX to the hex-encoded address bytes for the signing key (rather than the Bech32 address text). After signing, set SIGNATURE_HEX and COSE_KEY_HEX to the returned signature and key fields:

Terminal window
./bursa sign data --address "$ADDRESS_HEX" --payload 'Hello Cardano' \
--signing-key-file dev/payment.skey
./bursa sign verify --signature "$SIGNATURE_HEX" --key "$COSE_KEY_HEX" \
--payload 'Hello Cardano'

Use --payload-hex instead of --payload for binary data. Verification with the expected payload prints VALID on success and exits with an error if verification fails.

The signer command serves authenticated remote signing requests with configured custody backends, caller permissions, key policies, and anti-double-sign watermarks:

Terminal window
./bursa signer --config /path/to/signer.yaml

When --config is omitted, BURSA_CONFIG selects the YAML file. Configure at least one authentication mode; JWT bearer, mTLS client certificates, and authorized-key request signatures are supported. Before starting the service, follow the signer runbook and adapt the example signer configuration for custody, authentication, TLS, caller permissions, and durable watermarks. The signer overview links the API specification and security guidance.


Explore other Bursa Commands

Bursa Command Categories

  1. wallet   - Commands for generating wallet and the files needed to manage a Cardano wallet
  2. api     - Commands for running API
  3. kes-agent    - Commands for running the KES agent daemon for a Cardano block producer
  4. cert    - Commands for generating various Cardano certificates
  5. hash     - Commands for generating cryptographic hashes used in Cardano
  6. script    - Commands for multi-signature operations
  7. address - Commands for working with Cardano addresses
  8. key     - Commands for deriving individual keys from a mnemonic
  9. tx - Offline transaction operations
  10. sign - CIP-8/CIP-30 message signing and verification
  11. signer - Remote signing service


Doc Holiday logo

Docs authored by Doc Holiday