https://github.com/bitauth/bitauth-cli
universal identity and message authentication (WIP)
https://github.com/bitauth/bitauth-cli
Last synced: 18 days ago
JSON representation
universal identity and message authentication (WIP)
- Host: GitHub
- URL: https://github.com/bitauth/bitauth-cli
- Owner: bitauth
- Created: 2020-02-11T18:11:03.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-05T07:14:06.000Z (over 2 years ago)
- Last Synced: 2025-03-28T10:54:01.553Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://github.com/bitauth/bitauth2017/blob/master/bips/0-bitauth.mediawiki
- Size: 813 KB
- Stars: 8
- Watchers: 2
- Forks: 4
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
Awesome Lists containing this project
README
[](https://npmjs.org/package/@bitauth/cli)
[](https://circleci.com/gh/bitauth/bitauth-cli/tree/master)
[](https://ci.appveyor.com/project/bitauth/bitauth-cli/branch/master)
[](https://codecov.io/gh/bitauth/bitauth-cli)
[](https://npmjs.org/package/bitauth-cli)
# 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](https://nodejs.org/en/download/) v10 LTS or later, install the CLI globally:
```sh
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
```sh
bitauth verify path/to/file.zip.bitauth
```
(For details on the `.bitauth` file format, see [`docs/file-format.md`](/docs/file-format.md).)
# Usage Guide
This guide walks through key workflows using Bitauth CLI. A full [CLI Reference](#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.:
```sh
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:
```sh
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](https://free.bitcoin.com/)).
## 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:
```sh
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:
```sh
bitauth lookup [BITAUTH_ID]
```
Or:
```sh
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`](https://github.com/stedolan/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:
```sh
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:
```sh
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](src/internal/defaults/data-dir-readme.ts) 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.
Commands
Below you'll find the [`help`](#bitauth-help-command) output for all available commands.
- [`bitauth autocomplete [SHELL]`](#bitauth-autocomplete-shell)
- [`bitauth config`](#bitauth-config)
- [`bitauth hello [FILE]`](#bitauth-hello-file)
- [`bitauth help [COMMAND]`](#bitauth-help-command)
- [`bitauth update [CHANNEL]`](#bitauth-update-channel)
- [`bitauth wallet [FILE]`](#bitauth-wallet-file)
- [`bitauth wallet:new [WALLET_ID] [TEMPLATE_ID]`](#bitauth-walletnew-wallet_id-template_id)
## `bitauth autocomplete [SHELL]`
display autocomplete installation instructions
```
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
```
_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v0.1.5/src/commands/autocomplete/index.ts)_
## `bitauth config`
Display current Bitauth configuration
```
USAGE
$ bitauth config
OPTIONS
-h, --help show CLI help
DESCRIPTION
Longer description here
```
_See code: [src/commands/config.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/config.ts)_
## `bitauth hello [FILE]`
short 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!
```
_See code: [src/commands/hello.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/hello.ts)_
## `bitauth help [COMMAND]`
display help for bitauth
```
USAGE
$ bitauth help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
```
_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v2.2.3/src/commands/help.ts)_
## `bitauth update [CHANNEL]`
update the bitauth CLI
```
USAGE
$ bitauth update [CHANNEL]
```
_See code: [@oclif/plugin-update](https://github.com/oclif/plugin-update/blob/v1.3.9/src/commands/update.ts)_
## `bitauth wallet [FILE]`
short description here
```
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!
```
_See code: [src/commands/wallet/index.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/wallet/index.ts)_
## `bitauth wallet:new [WALLET_ID] [TEMPLATE_ID]`
short description here
```
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!
```
_See code: [src/commands/wallet/new.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/wallet/new.ts)_
# Contributing
Pull Requests welcome! Please see [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) for tips on getting started.