{"id":26181401,"url":"https://github.com/bitauth/bitauth-cli","last_synced_at":"2025-04-14T22:44:23.622Z","repository":{"id":42295258,"uuid":"239831074","full_name":"bitauth/bitauth-cli","owner":"bitauth","description":"universal identity and message authentication (WIP)","archived":false,"fork":false,"pushed_at":"2023-01-05T07:14:06.000Z","size":832,"stargazers_count":8,"open_issues_count":10,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T10:54:01.553Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/bitauth/bitauth2017/blob/master/bips/0-bitauth.mediawiki","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitauth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-11T18:11:03.000Z","updated_at":"2024-11-19T18:41:33.000Z","dependencies_parsed_at":"2023-02-03T17:16:20.523Z","dependency_job_id":null,"html_url":"https://github.com/bitauth/bitauth-cli","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitauth%2Fbitauth-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitauth%2Fbitauth-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitauth%2Fbitauth-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitauth%2Fbitauth-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitauth","download_url":"https://codeload.github.com/bitauth/bitauth-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248975291,"owners_count":21192198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-11T21:59:22.573Z","updated_at":"2025-04-14T22:44:23.600Z","avatar_url":"https://github.com/bitauth.png","language":"TypeScript","readme":"[![Version](https://img.shields.io/npm/v/@bitauth/cli.svg)](https://npmjs.org/package/@bitauth/cli)\n[![CircleCI](https://circleci.com/gh/bitauth/bitauth-cli/tree/master.svg?style=shield)](https://circleci.com/gh/bitauth/bitauth-cli/tree/master)\n[![Appveyor CI](https://ci.appveyor.com/api/projects/status/github/bitauth/bitauth-cli?branch=master\u0026svg=true)](https://ci.appveyor.com/project/bitauth/bitauth-cli/branch/master)\n[![Codecov](https://codecov.io/gh/bitauth/bitauth-cli/branch/master/graph/badge.svg)](https://codecov.io/gh/bitauth/bitauth-cli)\n[![Downloads/week](https://img.shields.io/npm/dw/bitauth-cli.svg)](https://npmjs.org/package/bitauth-cli)\n\n# bitauth-cli\n\n### Work In Progress: Please note, the documentation below is for planning and design purposes, and most commands are not yet implemented.\n\nBitauth is a universal identity and message authentication standard. This CLI provides commands for tracking identities, verifying signatures, and managing your own wallets and identities.\n\n# Quick Start\n\nWith [Node.js](https://nodejs.org/en/download/) v10 LTS or later, install the CLI globally:\n\n```sh\nnpm i -g @bitauth/cli\n```\n\nFor the best experience, run `bitauth autocomplete` and follow the instructions to enable autocompletion for your shell.\n\n## Verify a File\n\n```sh\nbitauth verify path/to/file.zip.bitauth\n```\n\n(For details on the `.bitauth` file format, see [`docs/file-format.md`](/docs/file-format.md).)\n\n# Usage Guide\n\nThis guide walks through key workflows using Bitauth CLI. A full [CLI Reference](#cli-reference) can be found below.\n\n## Create a Wallet\n\nTo create transactions or identities, we'll need a wallet. Get started using the interactive setup:\n\n```\nbitauth wallet new\n```\n\n\u003c!-- Outline:\n- What kind of wallet would you like to create? (new wallet types can be added with `bitauth template`)\n- (if template takes arguments, request them here)\n- (if ambiguous:) Which role will be performed by this wallet?\n- Enter a name for this wallet: (used in CLI output, e.g. \"Personal Wallet\")\n- Choose an alias for this wallet: (to refer to this wallet in CLI commands, e.g. \"personal\")\n\n(if entity requires variables which aren't keys:)\n  - How many addresses should be pre-generated?\n  - Please provide a value for `variable_name`: (First sentence of variable description) Footer: The remaining portion of the variable description as a hint. (Followed by) Result: [computed in hex and disassembled] | Error: [BTL compilation error]\n\n(Print full CLI command with dim text:)\nCreating wallet...\n$ bitauth wallet:new \"Personal Wallet\" \"personal\" --template=\"m-of-n\" --template-parameters=\"{m:2,n:2}\" --entity=\"owner\" --wallet-data=\"{wallet_var:'0x012345'}\" --address-data=\"[{addr_var: '1'}, {addr_var: '2'}]\"\n\nNew wallet \"Personal Wallet\" partially created at: $BITAUTH_DATA_DIR/wallets/personal\n\nFor details, run: `bitauth wallet personal`\n\n--json: {\n  path: '$BITAUTH_DATA_DIR/wallets/short-id',\n  status: 'partial'\n}\n --\u003e\n\nFor 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.\n\nWhen the setup is complete, confirm that the new wallet is in our list of wallets:\n\n```\nbitauth wallet\n```\n\n\u003c!--\n\n$ bitauth wallet\nUse \"bitauth wallet [ALIAS]\" to start interactive mode, or --help for details.\n\n**Bitauth Wallets**:\nAlias       Name              Role (if any differ)     Balance       Refreshed (if any differ)\npersonal    Personal Wallet   Owner                    1.000 BCH     2020-2-27 12:00 PM EST\nsecond      Another Wallet    Owner                    0.050 BCH\n(if Refreshed column is hidden:)\nRefreshed: 2020-2-27 12:00 PM EST\n\n--\u003e\n\nThis 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.:\n\n```sh\nbitauth wallet --json\n```\n\n\u003c!--\n\n{\n  \"wallets\": [\n    {\"alias\": \"personal\", \"name\": \"Personal Wallet\", \"role\": \"Owner\", \"balance\": \"1.000 BCH\", Refreshed: [Date]}\n  ]\n}\n\n --\u003e\n\nThis is helpful when using Bitauth CLI from scripts or other programs.\n\n## Fund an Address\n\nNow that the wallet has been created, we can generate an address to receive our first payment.\n\nWe can get the first unused address from the wallet interface – `[ALIAS]` is the identifier you chose during the interactive wallet setup:\n\n```sh\nbitauth wallet [ALIAS]\n```\n\n\u003c!--\nbold(Personal Wallet) (c.yellow(\"personal\"))\n\nlist addresses\n\nCommands:\n- rename\n- status (shown in interactive header)\n- refresh\n- address\n- outputs\n- listen\n\n --\u003e\n\nThe 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.\n\nThe 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/)).\n\n## Create an Identity\n\nNext, let's create our first identity using the interactive setup:\n\n```\nbitauth id new\n```\n\n\u003c!--\n - Enter a name for this Bitauth ID: (e.g. \"Satoshi Nakamoto\" or \"Company Name\")\n   - warn if longer than 50 characters\n - Choose an alias for this Bitauth ID: (to refer to it in CLI commands, e.g. \"me\")\n - Enter a description for this identity: [placeholder: \"Short bio or description for this identity\"] (optional)\n   - warn if longer than 100 characters\n - Would you like to broadcast this name and description on-chain? Make public / Don't share (by adding them to the public metadata for this identity)\n - Which wallet should hold the ownership output? (This wallet must sign to update the identity or change the signing output.)\n - Which wallet should hold the signing output? (This wallet may temporarily sign on behalf of the identity.)\n --\u003e\n\nFollow 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.\n\nWhen the setup is complete, confirm that the new ID is in our list of Bitauth IDs:\n\n```\nbitauth id\n```\n\n\u003c!--\nTODO: can we merge \"track\" into this?\n\nexample output:\n\nBitauth Identities\n==================\nAlias  Name               Wallet (/Ownership)    Signing (if any differ)    Updated\nme     Jason Dreyzehner   Personal Wallet        Another Wallet             2020-2-27 12:00PM EST\n\n --\u003e\n\nOur 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:\n\n```\nbitauth id [ALIAS]\n```\n\n\u003c!--\nbold(Jason Dreyzehner) (c.yellow(\"me\"))\nBitauth ID: [Pending first update] (later: `bitauth:qwtcxp42fcp06phz2xec6t5krau0ftew5efy50j9xyfxwa38df40zp58z6t5w`)\nComment: Short bio or description for this identity\n\nLast Update: 2020-2-27 12:00PM EST (/ c.dim(never))\n[Authhead TXID]\n\nCurrent Status\n==============\nOwnership: c.dim(none)\nPublic Metadata: c.dim(none)\n\nAfter Update\n============\nOwnership: Personal Wallet\nSigning Output: Another Wallet (only shown if different than Ownership)\nPublic Metadata:\n  Name: \"Jason Dreyzehner\"\n  Comment: \"Short bio or description for this identity\"\n\n**This identity has pending changes.**\nConfirm the changes are correct, then create the update transaction.\n\n- Create Update Transaction\n---- (separator)\n- Change Name, Alias, or Comment\n  - (Display enquirer multi-input form)\n  - (On confirm:) Would you like to update this identity's public metadata with these changes? (hint: The \"name\" and \"comment\" will be broadcasted on-chain.)\n- Edit Public Metadata (hint: Metadata is shared via an OP_RETURN output using the Bitauth Key-Value Protocol.)\n- Move Ownership Output (hint: This output must sign to create update transactions.)\n- Move Signing Output (hint: This output can sign on behalf of the identity.)\n- Exit (hint: You can also exit with Ctrl+C.)\n --\u003e\n\nThe 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.\n\n\u003c!--\n\ndoesn't have any options/interactivity – just creates the proposal.\n\n$ bitauth id:update [ALIAS]\nUpdate transaction proposal created for identity Jason Dreyzehner (\"me\").\n\nProposal ID: [uuid]\nAlias: me-0\n\nUse \"bitauth tx me-0\" to modify or broadcast.\n\n\n--json: {\n  \"update\": {\n    \"success\": true,\n    \"proposal\": \"[ID]\",\n    \"alias\": \"[ALIAS]\"\n  }\n}\n\n --\u003e\n\nNow let's confirm the transaction proposal was created:\n\n```sh\nbitauth tx\n```\n\n\u003c!--\n\n\nflags:\nfilter by wallet: --wallet=\"ALIAS\"\nfilter by identity: --id=\"ALIAS\"\nfilter by address: --address=\"ADDR\"\nonly proposals: --proposals\nonly history: --history\nshow both proposals and history: --proposals --history OR (neither flag)\nlimits to 20 items by default – no limit: --limit=0\n--json should work as expected\n\n● – signed\n(? ◍ – partially signed , ○ – finalized, or:)\n○ – partially signed\n\nexample output:\n\n$ bitauth tx\nTransaction Proposals                            ● signed   ○ partially signed\n=====================\n  Alias        Comment                                Created\n○ me-0         Update TX for \"Jason Dreyzehner\"       2020-2-27 12:00PM EST\n\n(if exists)\nTransaction History\n===================\n\n --\u003e\n\nOur new update transaction is now listed under `Transaction Proposals`. Let's fund it:\n\n```\nbitauth tx [ALIAS]\n```\n\n\u003c!--\n\n$ bitauth tx me-0\nTransaction Proposal: me-0\nComment: Identity Update TX for \"Jason Dreyzehner\"\nCreated: 2020-2-27 12:00PM EST\n\nInputs: c.dim(none)\n\nOutputs:\n● 0: 0.001 BCH – Personal Wallet (:1)\n  1: 0.001 BCH – Another Wallet (:1)\n  2: 0 BCH – OP_RETURN (BKVP Metadata)\ndim(● change output)\n\n(blocking issues shown here:)\n**This transaction has not been funded.** Add at least one input to continue.\n\n- Edit Inputs/Outputs\n---- (required/recommended actions shown above separator)\n- Change Alias or Comment\n- Export Proposal\n- Import\n- Exit (hint: You can also exit with Ctrl+C.)\n\n\n\n------------------\n(Inputs which include Ownership Outputs from tracked identities:)\n\nInputs:\n  0: 0.01 BCH – Personal Wallet (:1) → bold(Jason Dreyzehner (\"me\")), bold(Another Merged One (\"another\"))\n\n(Warnings section – non-blocking issues)\nWarnings:\n  - This transaction proposal modifies the identity: Jason Dreyzehner (\"me\")\n  - This transaction proposal modifies the identity: Another Merged One (\"another\")\n\n\n  - (OP_RETURN in 0th output + tracked identities:) This transaction permanently destroys and identity: Identity Name (\"alias\") - The Ownership (0th) output is un-spendable.\n  -\n\n\n ({'n':'Jason Dreyzehner', 'c': ''})\n\n --\u003e\n\nThe interactive transaction interface allows you to edit inputs and outputs\n\n## Sign a File\n\n```\nbitauth sign [FILE_PATH]\n```\n\n## Migrate an Identity\n\n[describe upgrading an identity to multisig]\n\n### Create a Multisig Wallet\n\n### Create the Migration Transaction\n\n## Broadcast Metadata for an Identity\n\n### Add Metadata to the Identity\n\n### Create the Migration Transaction\n\n## Lookup an Identity\n\nOccasionally you'll need to quickly lookup an identity. Find the entity's Bitauth ID, e.g. `bitauth:qwtcxp42fcp06phz2xec6t5krau0ftew5efy50j9xyfxwa38df40zp58z6t5w`, then:\n\n```sh\nbitauth lookup [BITAUTH_ID]\n```\n\nOr:\n\n```sh\nbitauth lookup [BITAUTH_ID] --json\n```\n\nThis 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.\n\n## Track an Identity\n\nFor identities you'll lookup again in the future – like software signing identities – you should track the identity:\n\n```sh\nbitauth track [BITAUTH_ID]\n```\n\nThis 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.\n\nYou'll now find the new identity in our list of tracked identities:\n\n```\nbitauth track\n```\n\n\u003c!--\nicon ideas:\n● – ownership\n◍ – confirming ownership output\n○ – signing\n◌ – confirming signing output\n\n\nTracked Bitauth Identities      (show when visible:)    ● ownership   ○ signing\n==========================\n\n  Name                  Comment                                       Alias  (default 7, up to first different char)\n○ Another Identity      That one's description                        qwtcxp42...\n● Jason Dreyzehner      Short bio or description for this identity    me\n\n--json:\n\n{\n  \"identities\": [\n    {\"name\": \"Another Identity\", \"comment\": \"That one's description\", \"ownership\": false, \"signing\": \"personal\"},\n    {\"name\": \"Jason Dreyzehner\", \"comment\": \"Short bio or description for this identity\", \"ownership\": \"personal\", \"signing\": \"personal\"},\n    {\"name\": \"Someone Else\", \"comment\": \"the comment I added\", \"ownership\": false, \"signing\": false}\n  ]\n}\n\n\n --\u003e\n\n## Switch Bitauth Data Directories\n\nAll wallets, data, and configuration are stored in your Bitauth data directory. To show the data directory currently in use, run:\n\n```\nbitauth config --data-dir\n```\n\nThis can be configured using the `$BITAUTH_DATA_DIR` environment variable:\n\n```sh\nexport BITAUTH_DATA_DIR='~/another/data-directory';\nbitauth config --data-dir\n# =\u003e /Users/me/another/data-directory\n```\n\nUsing multiple data directories can be helpful for separating domains of wallets, e.g. \"business\" and \"personal\".\n\nFor more information on the contents of the Bitauth data directory, see [the readme](src/internal/defaults/data-dir-readme.ts) generated in your own:\n\n```\ncat $(bitauth config --data-dir)/readme.md\n```\n\n# CLI Reference\n\nBitauth CLI includes commands to create and manage Bitauth identities, sign files and messages, verify existing Bitauth signatures, and more.\n\n\u003c!-- disable:usage --\u003e\n\u003c!-- disable:usagestop --\u003e\n\n\u003c!-- disable:toc --\u003e\n\u003c!-- disable:tocstop --\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCommands\u003c/strong\u003e\u003c/summary\u003e\n\nBelow you'll find the [`help`](#bitauth-help-command) output for all available commands.\n\n\u003c!-- commands --\u003e\n\n- [`bitauth autocomplete [SHELL]`](#bitauth-autocomplete-shell)\n- [`bitauth config`](#bitauth-config)\n- [`bitauth hello [FILE]`](#bitauth-hello-file)\n- [`bitauth help [COMMAND]`](#bitauth-help-command)\n- [`bitauth update [CHANNEL]`](#bitauth-update-channel)\n- [`bitauth wallet [FILE]`](#bitauth-wallet-file)\n- [`bitauth wallet:new [WALLET_ID] [TEMPLATE_ID]`](#bitauth-walletnew-wallet_id-template_id)\n\n## `bitauth autocomplete [SHELL]`\n\ndisplay autocomplete installation instructions\n\n```\nUSAGE\n  $ bitauth autocomplete [SHELL]\n\nARGUMENTS\n  SHELL  shell type\n\nOPTIONS\n  -r, --refresh-cache  Refresh cache (ignores displaying instructions)\n\nEXAMPLES\n  $ bitauth autocomplete\n  $ bitauth autocomplete bash\n  $ bitauth autocomplete zsh\n  $ bitauth autocomplete --refresh-cache\n```\n\n_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v0.1.5/src/commands/autocomplete/index.ts)_\n\n## `bitauth config`\n\nDisplay current Bitauth configuration\n\n```\nUSAGE\n  $ bitauth config\n\nOPTIONS\n  -h, --help  show CLI help\n\nDESCRIPTION\n  Longer description here\n```\n\n_See code: [src/commands/config.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/config.ts)_\n\n## `bitauth hello [FILE]`\n\nshort description here\n\n```\nUSAGE\n  $ bitauth hello [FILE]\n\nOPTIONS\n  -f, --force\n  -h, --help       show CLI help\n  -n, --name=name  name to print\n\nDESCRIPTION\n  Longer description here\n\nEXAMPLE\n  $ bitauth hello\n  hello world from ./src/hello.ts!\n```\n\n_See code: [src/commands/hello.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/hello.ts)_\n\n## `bitauth help [COMMAND]`\n\ndisplay help for bitauth\n\n```\nUSAGE\n  $ bitauth help [COMMAND]\n\nARGUMENTS\n  COMMAND  command to show help for\n\nOPTIONS\n  --all  see all commands in CLI\n```\n\n_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v2.2.3/src/commands/help.ts)_\n\n## `bitauth update [CHANNEL]`\n\nupdate the bitauth CLI\n\n```\nUSAGE\n  $ bitauth update [CHANNEL]\n```\n\n_See code: [@oclif/plugin-update](https://github.com/oclif/plugin-update/blob/v1.3.9/src/commands/update.ts)_\n\n## `bitauth wallet [FILE]`\n\nshort description here\n\n```\nUSAGE\n  $ bitauth wallet [FILE]\n\nOPTIONS\n  -h, --help  show CLI help\n\nDESCRIPTION\n  Longer description here\n\nALIASES\n  $ bitauth wallets\n\nEXAMPLE\n  $ bitauth wallet\n  hello world from ./src/hello.ts!\n```\n\n_See code: [src/commands/wallet/index.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/wallet/index.ts)_\n\n## `bitauth wallet:new [WALLET_ID] [TEMPLATE_ID]`\n\nshort description here\n\n```\nUSAGE\n  $ bitauth wallet:new [WALLET_ID] [TEMPLATE_ID]\n\nARGUMENTS\n  WALLET_ID    wallet identifier\n  TEMPLATE_ID  authentication template identifier\n\nOPTIONS\n  -h, --help  show CLI help\n\nDESCRIPTION\n  Longer description here\n\nEXAMPLE\n  $ bitauth wallet new\n  hello world from ./src/hello.ts!\n```\n\n_See code: [src/commands/wallet/new.ts](https://github.com/bitauth/bitauth-cli/blob/v0.0.0/src/commands/wallet/new.ts)_\n\n\u003c!-- commandsstop --\u003e\n\n\u003c/details\u003e\n\n# Contributing\n\nPull Requests welcome! Please see [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) for tips on getting started.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitauth%2Fbitauth-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitauth%2Fbitauth-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitauth%2Fbitauth-cli/lists"}