diff --git a/usage-guide.md b/usage-guide.md new file mode 100644 index 0000000..e6c60de --- /dev/null +++ b/usage-guide.md @@ -0,0 +1,277 @@ +## Turnkey CLI (tkcli) Command Guide + +`tkcli` is a command-line interface tool for interacting with the Turnkey API. It allows you to manage activities, keys, wallets, and more directly from your terminal. + +### Persistent Flags + +The following flags can be used with most `tkcli` commands: + +- `--keys-folder`, `-d `: Specifies the directory in which to locate API keys (defaults to a standard location). +- `--encryption-keys-folder `: Specifies the directory in which to locate encryption keys (defaults to a standard location). +- `--key-name`, `-k `: Specifies the name of the API key to use for interacting with the Turnkey API service (defaults to "default"). +- `--encryption-key-name `: Specifies the name of the encryption key to use (defaults to "default"). +- `--host `: Specifies the hostname of the API server (defaults to "api.turnkey.com"). +- `--organization `: Specifies the organization ID to interact with. This is often required. +- `--output`, `-o `: Specifies the output format. Available formats are `json` (default) and `yaml`. + +### Command Reference + +#### `activities` + +Interact with the API activities. + +- __`list`__: Return the set of activities for an organization. + + - Flags: + - `--status `: Only include activities whose status is declared in this set. Available statuses: `created`, `pending`, `completed`, `failed`, `consensus`, `consensus_needed`, `rejected`, `all`. + - Example: `tkcli activities list --status completed,failed` + +- __`get `__: Return the details and status of a particular activity. + + - Arguments: + - ``: The ID of the activity to retrieve. + - Example: `tkcli activities get ` + +#### `curves` + +Interact with the available curves. + +- __`list`__: Return the available curve types. + - Example: `tkcli curves list` + +#### `decrypt` + +Decrypt a ciphertext from a bundle exported from a Turnkey secure enclave. + +- Flags: + + - `--export-bundle-input `: Filepath to read the export bundle from (Required). + - `--plaintext-output `: Optional filepath to write the plaintext to. + - `--signer-quorum-key `: Optional override for the signer quorum key (for testing only). + - `--solana-address
`: Optional Solana address, for use when exporting Solana private keys in the proper format. + +- Example: `tkcli decrypt --export-bundle-input ./export-bundle.txt --plaintext-output ./decrypted-key.txt` + +#### `encrypt` + +Encrypt a plaintext into a bundle to be imported to a Turnkey secure enclave. + +- Flags: + + - `--import-bundle-input `: Filepath to read the import bundle from (result of `init-import`) (Required). + - `--encrypted-bundle-output `: Filepath to write the encrypted bundle to (Required). + - `--plaintext-input `: Filepath to read the plaintext from that will be encrypted (Required). + - `--key-format `: Optional formatting to apply to the plaintext before it is encrypted. Available formats: `mnemonic` (default), `hexadecimal`, `solana`. + - `--user `: ID of the user encrypting the plaintext (Required). + - `--signer-quorum-key `: Optional override for the signer quorum key (for testing only). + +- Example: `tkcli encrypt --import-bundle-input ./import-bundle.txt --encrypted-bundle-output ./encrypted-bundle.txt --plaintext-input ./plaintext-key.txt --user ` + +#### `ethereum` (`eth`) + +Perform actions related to Ethereum. + +- __`transaction` (`tx`)__: Perform signing and other actions for a transaction. + + - Flags: + + - `--signer`, `-s `: Wallet account address, private key address, or private key ID (Required). + - `--payload `: Payload of the transaction (Required). + + - Example: `tkcli eth tx --signer --payload ` + +#### `generate` + +Generate keys. + +- __`api-key`__: Generate a Turnkey API key. + + - Flags: + + - `--curve `: Curve type for API key. Supported types: `p256` (default), `secp256k1`, and `ed25519`. + - `--organization `: Organization ID (Required). + + - Example: `tkcli generate api-key --organization --curve secp256k1` + +- __`encryption-key`__: Generate a Turnkey encryption key. + + - Flags: + + - `--user `: ID of user generating the encryption key (Required). + - `--organization `: Organization ID (Required). + + - Example: `tkcli generate encryption-key --user --organization ` + +#### `organizations` (`o`, `org`, `organization`) + +Interact with organizations stored in Turnkey. + +- __`create`__: Create a new organization. + + - Flags: + - `--name `: Name of the organization (Required). + - *Note: Based on the code, this command appears to be implemented to create private keys instead of an organization.* + - Example: `tkcli organizations create --name "My New Org"` + +#### `private-keys` (`pk`) + +Interact with private keys. + +- __`create`__: Create a new private key. + + - Flags: + + - `--address-format `: Address format(s) for private key (Required). Use `tkcli address-formats list` for available formats. + - `--curve `: Curve to use for the generation of the private key (Required). Use `tkcli curves list` for available curves. + - `--name `: Name to be applied to the private key (Required). + - `--tag `: Tag(s) to be applied to the private key. + + - Example: `tkcli private-keys create --address-format ethereum --curve secp256k1 --name "My Eth Key"` + +- __`list`__: Return private keys for the organization. + + - Example: `tkcli private-keys list` + +- __`export`__: Export a private key. + + - Flags: + + - `--id `: Name or ID of private key to export (Required). + - `--encryption-key-name `: Name of the encryption key to use (Required). + - `--export-bundle-output `: Filepath to write the export bundle to (Required). + + - Example: `tkcli private-keys export --id "My Eth Key" --encryption-key-name default --export-bundle-output ./private-key-export.txt` + +- __`init-import`__: Initialize private key import. + + - Flags: + + - `--user `: ID of user importing the private key (Required). + - `--import-bundle-output `: Filepath to write the import bundle to (Required). + + - Example: `tkcli private-keys init-import --user --import-bundle-output ./private-key-import-bundle.txt` + +- __`import`__: Import a private key. + + - Flags: + + - `--user `: ID of user importing the private key (Required). + - `--encrypted-bundle-input `: Filepath to read the encrypted bundle from (Required). + - `--address-format `: Address format(s) for private key (Required). + - `--curve `: Curve to use for the generation of the private key (Required). + - `--name `: Name to be applied to the private key (Required). + + - Example: `tkcli private-keys import --user --encrypted-bundle-input ./encrypted-private-key.txt --address-format ethereum --curve secp256k1 --name "Imported Eth Key"` + +#### `raw` + +Send low-level (raw) requests to the Turnkey API. + +- __`sign`__: Sign a raw payload. + + - Flags: + + - `--signer`, `-s `: Wallet account address, private key address, or private key ID (Required). + - `--payload `: Payload to be signed (Required). + - `--payload-encoding `: Encoding of payload (defaults to `text/utf8`). + - `--hash-function `: Hash function (defaults to `sha256`). + + - Example: `tkcli raw sign --signer --payload "Hello, Turnkey!"` + +#### `request` (`req`, `r`) + +Given a request body, generate a stamp for it, and send it to the Turnkey API server. + +- Flags: + + - `--path `: Path for the API request (Required). + - `--body `: Body of the request. Can be `-` for stdin or prefixed with `@` for a filename (defaults to `-`). + - `--no-post`: Generates the stamp and displays the cURL command but does NOT post the request. + +- Example: `tkcli request --path /v1/my-endpoint --body '{"data": "some data"}'` + +#### `transaction-types` + +Interact with the available transaction types. + +- __`list`__: Return the available transaction types. + - Example: `tkcli transaction-types list` + +#### `version` + +Display build and version information. + +- Example: `tkcli version` + +#### `wallets` + +Interact with wallets. + +- __`create`__: Create a new wallet. + + - Flags: + - `--name `: Name to be applied to the wallet (Required). + - Example: `tkcli wallets create --name "My New Wallet"` + +- __`list`__: Return wallets for the organization. + + - Example: `tkcli wallets list` + +- __`export`__: Export a wallet. + + - Flags: + + - `--name `: Name or ID of wallet to export (Required). + - `--encryption-key-name `: Name of the encryption key to use (Required). + - `--export-bundle-output `: Filepath to write the export bundle to (Required). + + - Example: `tkcli wallets export --name "My New Wallet" --encryption-key-name default --export-bundle-output ./wallet-export.txt` + +- __`init-import`__: Initialize wallet import. + + - Flags: + + - `--user `: ID of user importing the wallet (Required). + - `--import-bundle-output `: Filepath to write the import bundle to (Required). + + - Example: `tkcli wallets init-import --user --import-bundle-output ./wallet-import-bundle.txt` + +- __`import`__: Import a wallet. + + - Flags: + + - `--user `: ID of user importing the wallet (Required). + - `--name `: Name to be applied to the wallet (Required). + - `--encrypted-bundle-input `: Filepath to read the encrypted bundle from (Required). + + - Example: `tkcli wallets import --user --name "Imported Wallet" --encrypted-bundle-input ./encrypted-wallet.txt` + +- __`accounts` (`acc`)__: Interact with wallet accounts. + + - __`list`__: Return accounts for the wallet. + + - Flags: + - `--wallet `: Name or ID of wallet used to fetch accounts (Required). + - Example: `tkcli wallets accounts list --wallet "My New Wallet"` + + - __`create`__: Create a new account for a wallet. + + - Flags: + + - `--wallet `: Name or ID of wallet used for account creation (Required). + - `--address-format `: Address format for account (Required). Use `tkcli address-formats list` for available formats. + - `--curve `: Curve for account. If unset, will predict based on address format. Use `tkcli curves list` for available curves. + - `--path-format `: The derivation path format for account (defaults to `bip32`). + - `--path `: The derivation path for account. If unset, will predict next path. + + - Example: `tkcli wallets accounts create --wallet "My New Wallet" --address-format ethereum` + + - __`export`__: Export a wallet account. + + - Flags: + + - `--address
`: Address of wallet account to export (Required). + - `--encryption-key-name `: Name of the encryption key to use (Required). + - `--export-bundle-output `: Filepath to write the export bundle to (Required). + + - Example: `tkcli wallets accounts export --address --encryption-key-name default --export-bundle-output ./wallet-account-export.txt`