bitauth-cli

Work In Progress: Please note, the documentation below is for planning and design purposes, and most commands are not yet implemented.

Bitauth is a universal identity and message authentication standard. This CLI provides commands for tracking identities, verifying signatures, and managing your own wallets and identities.

Quick Start

With Node.js v10 LTS or later, install the CLI globally:

npm i -g @bitauth/cli

For the best experience, run bitauth autocomplete and follow the instructions to enable autocompletion for your shell.

Verify a File

bitauth verify path/to/file.zip.bitauth

(For details on the .bitauth file format, see docs/file-format.md.)

Usage Guide

This guide walks through key workflows using Bitauth CLI. A full CLI Reference can be found below.

Create a Wallet

To create transactions or identities, we'll need a wallet. Get started using the interactive setup:

bitauth wallet new

For our first wallet, let's choose the wallet type: Single Signature (P2PKH). Follow the remaining prompts to choose a name and an alias for the wallet.

When the setup is complete, confirm that the new wallet is in our list of wallets:

bitauth wallet

This lists all of our wallets and their current status. Most Bitauth CLI commands can also return results in JSON format using the --json flag, e.g.:

bitauth wallet --json

This is helpful when using Bitauth CLI from scripts or other programs.

Fund an Address

Now that the wallet has been created, we can generate an address to receive our first payment.

We can get the first unused address from the wallet interface – [ALIAS] is the identifier you chose during the interactive wallet setup:

bitauth wallet [ALIAS]

The interactive wallet interface also allows you to select from a list of actions to perform on the wallet. For now, you can simply exit out with Ctrl+C or by choosing the Exit option.

The address begins with bitcoincash:, and is followed by a long string of letters and numbers. Copy this address, paste it into another wallet, and send a small amount of BCH (or use a free faucet like the Bitcoin.com faucet).

Create an Identity

Next, let's create our first identity using the interactive setup:

bitauth id new

Follow the prompts to choose a name, short identifier, and description for the Bitauth ID. When prompted, choose the wallet we created for both the identity and signing outputs.

When the setup is complete, confirm that the new ID is in our list of Bitauth IDs:

bitauth id

Our new ID is listed, but its Updated column is marked as Pending.... Let's create our first update transaction to broadcast it – [ALIAS] is the alias you chose during the interactive setup:

bitauth id [ALIAS]

The interactive identity interface allows us to select from a list of actions to perform on the identity. Choose Create Update Transaction to create our first update transaction.

Now let's confirm the transaction proposal was created:

bitauth tx

Our new update transaction is now listed under Transaction Proposals. Let's fund it:

bitauth tx [ALIAS]

The interactive transaction interface allows you to edit inputs and outputs

Sign a File

bitauth sign [FILE_PATH]

Migrate an Identity

[describe upgrading an identity to multisig]

Create a Multisig Wallet

Create the Migration Transaction

Broadcast Metadata for an Identity

Add Metadata to the Identity

Create the Migration Transaction

Lookup an Identity

Occasionally you'll need to quickly lookup an identity. Find the entity's Bitauth ID, e.g. bitauth:qwtcxp42fcp06phz2xec6t5krau0ftew5efy50j9xyfxwa38df40zp58z6t5w, then:

bitauth lookup [BITAUTH_ID]

Or:

bitauth lookup [BITAUTH_ID] --json

This will show the latest information for the specified identity. As with most commands, the --json flag causes results to be returned in JSON format. You can use a program like jq to manipulate the output.

Track an Identity

For identities you'll lookup again in the future – like software signing identities – you should track the identity:

bitauth track [BITAUTH_ID]

This initiates a short setup process to track the identity. If the identity is a contact you already know or a public entity, you should use multiple sources to confirm it is the correct Bitauth ID, e.g. the entity's website, social media, or direct communications.

You'll now find the new identity in our list of tracked identities:

bitauth track

Switch Bitauth Data Directories

All wallets, data, and configuration are stored in your Bitauth data directory. To show the data directory currently in use, run:

bitauth config --data-dir

This can be configured using the $BITAUTH_DATA_DIR environment variable:

export BITAUTH_DATA_DIR='~/another/data-directory';
bitauth config --data-dir
# => /Users/me/another/data-directory

Using multiple data directories can be helpful for separating domains of wallets, e.g. "business" and "personal".

For more information on the contents of the Bitauth data directory, see the readme generated in your own:

cat $(bitauth config --data-dir)/readme.md

CLI Reference

Bitauth CLI includes commands to create and manage Bitauth identities, sign files and messages, verify existing Bitauth signatures, and more.

USAGE
  $ bitauth autocomplete [SHELL]

ARGUMENTS
  SHELL  shell type

OPTIONS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

EXAMPLES
  $ bitauth autocomplete
  $ bitauth autocomplete bash
  $ bitauth autocomplete zsh
  $ bitauth autocomplete --refresh-cache

USAGE
  $ bitauth config

OPTIONS
  -h, --help  show CLI help

DESCRIPTION
  Longer description here

USAGE
  $ bitauth hello [FILE]

OPTIONS
  -f, --force
  -h, --help       show CLI help
  -n, --name=name  name to print

DESCRIPTION
  Longer description here

EXAMPLE
  $ bitauth hello
  hello world from ./src/hello.ts!

USAGE
  $ bitauth help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

USAGE
  $ bitauth update [CHANNEL]

USAGE
  $ bitauth wallet [FILE]

OPTIONS
  -h, --help  show CLI help

DESCRIPTION
  Longer description here

ALIASES
  $ bitauth wallets

EXAMPLE
  $ bitauth wallet
  hello world from ./src/hello.ts!

USAGE
  $ bitauth wallet:new [WALLET_ID] [TEMPLATE_ID]

ARGUMENTS
  WALLET_ID    wallet identifier
  TEMPLATE_ID  authentication template identifier

OPTIONS
  -h, --help  show CLI help

DESCRIPTION
  Longer description here

EXAMPLE
  $ bitauth wallet new
  hello world from ./src/hello.ts!

Contributing

Pull Requests welcome! Please see CONTRIBUTING.md for tips on getting started.