PayString CLI
note
PayString was previously known as PayID.
With the PayString CLI, you can run PayString commands from the command line, and access all PayString features.
View the PayString CLI project on Github.
#
PayString CLI setupPayString CLI uses TypeScript. Therefore, make sure you have installed node and the npm package manager locally.
To install PayString CLI, run:
npm install -g @payid-org/payid-cli
This command installs PayString CLI as a global npm module and links it as an executable, typically under
/usr/local/bin/payid
.
To install and run PayString CLI from Docker, run:
docker run xpring/payid-cli
#
Run PayString CLI in interactive or single-command modeTo run PayString CLI in interactive mode, run payid
to open an interactive session.
In interactive mode, you can then run PayString CLI commands as desired with the form
<command> <arguments>
, such as:
load 'nhartner$xpring.money'
To exit interactive mode, run exit
.
To run PayString CLI in single-command mode, prefix each command with payid
. Each command takes the form
payid <command> <arguments>
, such as:
payid load 'nhartner$xpring.money'
Use single-command mode for scripts, or to chain the results of multiple commands together, such as:
payid init 'my$pay.id' && payid crypto-address add btc mainnet notARealAddress && payid save
When you pass a PayString as an argument in non-interactive mode, make sure to escape or quote the PayString to avoid the '$'
being interpolated as a variable by the shell.
#
Example commandsTip: If you obtain an XRP testnet wallet, you get a PayString based on your RippleX account that is already linked to an XRP address. This is useful for testing. Visit the RippleX.io portal and sign in with Github. The RippleX portal launchpad page opens. Click XRP Testnet Wallet and follow the steps to create your wallet. Your PayString has the form <github-username>$xpring.money
and you can use this PayString value in these example commands.
#
Load a PayStringThis command loads the specified PayString from a remote server.
load loisrp$xpring.money
The output fetches all the PayString address mappings for the given PayString from the remote server and displays the resulting JSON. In this example, the PayString has two crypto-addresses attached to it.
#
Remove a crypto-addressIf you have previously loaded a PayString, you can use this command to remove a crypto-address attached to it.
crypto-address remove "rwcBVJwXdXusY5SgNMjHbMWbR2Nnt2U3R6"
The output returns the updated information about the PayString. In this example, the command removed the address on XRP testnet.
#
Add a crypto-addressYou can add a crypto-address to a PayString. This command does not confirm the validity of the address details.
crypto-address add xrpl mainnet rP3t3JStqWPYd8H88WfBYh3v84qqYzbHQ6 12345
The output returns the updated information for the PayString, including the added crypto-address.
#
Create a new PayStringThe following set of commands demonstrates how to create a new PayString, attach multiple address mappings, and save the result to a JSON file.
The PayString JSON representation specified here is saved to the local filesystem as example.json.
#
Manage identity keysThe PayString protocol supports signing address mappings using one or more cryptographic keys. PayString CLI provides several commands to generate and load keys. Once a key is generated or loaded by PayString CLI, it is retained in PayString CLI's local storage for use when you sign your PayString.
You can generate multiple identity keys by using the keys generate
and keys load
commands.
To remove all loaded keys from the CLI's local storage, use the keys clear
command. To see all keys currently loaded into PayString CLI, use the keys list
command.
#
Generate a new key runThis generates a new key and saves it to a file named identity-key.pem. To load a previously created identity key, run
keys load </path/to/pem/file>
.
#
Sign a PayStringBefore you sign an PayString, you must either load the PayString using the load
command, or create a PayString using the init
command, and you must execute commands to add one or more crypto-addresses to the PayString.
Once a PayString has been initialized or loaded, you can sign it using an identity key. You must either generate a new key, or load an existing one. Once your PayString has been loaded or initialized, and your identity key has been generated or loaded, you can sign the PayString using the sign
command. The sign
command signs each of your PayString address mappings using the loaded identity keys, and outputs the resulting PayString with a verifiedAddress
field. Run the save
command to save your PayString, with signed addresses, to file.
#
Inspect a Verified PayStringTwo commands are available to verify a PayString's verified addresses.
verify
- Checks if all the verified addresses have valid signatures.
inspect
- Displays details information about each verified address and signatures.
#
Create, sign, and verify a PayStringWith this combination of commands, you can create a PayString, add an address mapping, generate an identity key, sign your PayString address mapping, and then inspect the final result. You can check the output after each command.