From d1ccacba8f50f4b5f7d56aff749467c5fa20350e Mon Sep 17 00:00:00 2001 From: Aryan Jassal Date: Tue, 17 Dec 2024 13:51:16 +1100 Subject: [PATCH] chore: updating secrets commands to match current implementation chore: updated vaults commands chore: updated grammar --- docs/reference/polykey-cli/commands/README.md | 118 +++++----- .../reference/polykey-cli/commands/secrets.md | 217 ++++++++++++++---- docs/reference/polykey-cli/commands/vaults.md | 141 +++++------- docs/tutorials/polykey-cli/installation.md | 34 +-- 4 files changed, 310 insertions(+), 200 deletions(-) diff --git a/docs/reference/polykey-cli/commands/README.md b/docs/reference/polykey-cli/commands/README.md index 29599823..371c8619 100644 --- a/docs/reference/polykey-cli/commands/README.md +++ b/docs/reference/polykey-cli/commands/README.md @@ -19,18 +19,18 @@ The bootstrap subcommand solely deals with the construction of the state of poly The supplied or assumed node path must exist and be empty for a successful execution, otherwise the command will exit with code [EX_USAGE (64)]. | Command | Description | Level | Interaction | -| --------- | ----------------------------------------- | ----- | ----------- | -| bootstrap | Initializes a PolyKey node at a node path | 1 | Local | +|-----------|-------------------------------------------|-------|-------------| +| bootstrap | Initializes a Polykey node at a node path | 1 | Local | ### Agent The agent subcommand allows control over the Polykey agent process. | Command | Description | Level | Interaction | -| ------- | --------------------------------------- | ----- | ----------- | -| start | Starts the PolyKey Agent | 1 | Local | -| stop | Stops the PolyKey Agent | 1 | Local | -| status | Gets the status of the PolyKey Agent | 1 | Local | +|---------|-----------------------------------------|-------|-------------| +| start | Starts the Polykey Agent | 1 | Local | +| stop | Stops the Polykey Agent | 1 | Local | +| status | Gets the status of the Polykey Agent | 1 | Local | | unlock | Starts a session for the current client | 1 | Local | | lock | Locks the current client session | 1 | Local | | lockall | Locks all active sessions on the agent | 1 | Local | @@ -39,19 +39,19 @@ The agent subcommand allows control over the Polykey agent process. The vaults subcommand will deal with CRUD (Create, read, update and delete) operations on Polykey vaults. -| Command | Description | Level | Interaction | -| ----------- | ----------------------------------- | ----- | ----------- | -| create | Creates a new vault | 1 | Local | -| delete | Deletes an existing vault | 1 | Local | -| list | Lists all existing vaults | 1 | Local | -| rename | Renames an existing vault | 1 | Local | -| stats | Gets the stats of an existing vault | 1 | Local | -| share | Shares vaults with a gestalt | 1 | Local | -| unshare | Unshares vaults with a gestalt | 1 | Local | -| permissions | Gets the permissions for a vault | 1 | Local | -| pull | Pulls a vault from another node | 1 | Agent-Agent | -| scan | Lists the vaults of another node | 1 | Agent-Agent | -| clone | Clones a vault from another node | 1 | Agent-Agent | +| Command | Description | Level | Interaction | +|--------------|-------------------------------------|-------|-------------| +| create | Creates a new vault | 1 | Local | +| rm \| remove | Removes an existing vault | 1 | Local | +| ls \| list | Lists all existing vaults | 1 | Local | +| rename | Renames an existing vault | 1 | Local | +| stats | Gets the stats of an existing vault | 1 | Local | +| share | Shares vaults with a gestalt | 1 | Local | +| unshare | Unshares vaults with a gestalt | 1 | Local | +| permissions | Gets the permissions for a vault | 1 | Local | +| pull | Pulls a vault from another node | 1 | Agent-Agent | +| scan | Lists the vaults of another node | 1 | Agent-Agent | +| clone | Clones a vault from another node | 1 | Agent-Agent | ### Secrets @@ -59,18 +59,18 @@ The secrets subcommand will deal with CRUD (Create, read, update and delete) ope As secrets subcommands are performed within a single vault, paths are specified using the following notation `:`. As each vault maintains separate filesystems, secrets cannot be transferred across vaults. -| Command | Description | Level | Interaction | -| ------- | ------------------------------------------------ | ----- | ----------- | -| create | Creates a new secret | 1 | Local | -| delete | Deletes an existing secret | 1 | Local | -| edit | Edits an existing secret | 1 | Local | -| get | Gets the contents of an existing secret | 1 | Local | -| list | Lists the secrets within an existing vault | 1 | Local | -| mkdir | Makes a directory inside an existing vault | 1 | Local | -| dir | Adds a directory of secrets to an existing vault | 1 | Local | -| rename | Renames an existing secret | 1 | Local | -| update | Updates an existing secret with new content | 1 | Local | -| env | Injects existing secrets into an environment | 2 | Local | +| Command | Description | Level | Interaction | +|--------------|-----------------------------------------------------------------------|-------|-------------| +| create | Creates a new secret | 1 | Local | +| rm \| remove | Removes an existing secret | 1 | Local | +| ed \| edit | Edits an existing secret or creates one if it doesn't exist | 1 | Local | +| cat | Gets the contents of one or more secrets | 1 | Local | +| ls \| list | Lists the secrets within an existing directory | 1 | Local | +| mkdir | Makes a directory inside an existing vault | 1 | Local | +| dir | Adds a directory of secrets to an existing vault | 1 | Local | +| rename | Renames an existing secret | 1 | Local | +| write | Updates an existing secret with new content taken from standard input | 1 | Local | +| env | Injects existing secrets into an environment | 2 | Local | ### Keys @@ -83,7 +83,7 @@ Encryption using the root keypair has a size limit depending on the size of the For signature and verification using the root keypair, the data and signature will be input and output separately. In the future, this will be done using a specific file format which allows the signature and data to be compiled into one file. | Command | Description | Level | Interaction | -| --------- | ------------------------------------------- | ----- | ----------- | +|-----------|---------------------------------------------|-------|-------------| | cert | Gets the root certificate | 1 | Local | | certchain | Get the certificate chain | 1 | Local | | root | Get the root keypair | 1 | Local | @@ -99,38 +99,40 @@ For signature and verification using the root keypair, the data and signature wi The node subcommand allows manipulation of Polykey's peer-to-peer system. -| Command | Description | Level | Interaction | -| --------------- | ---------------------------------------- | ----- | ----------- | -| add | Adds a node to the node graph | 1 | Local | -| delete(Removed) | Deletes a node from the node graph | 1 | Local | -| get(Removed) | Gets the node info for a particular node | 1 | Local | -| claim | Makes a claim to a node | 1 | Agent-Agent | -| unclaim | Removes a claim to a ndoe | 1 | Agent-Agent | -| find | Attempts to find a node in the DHT | 1 | Agent-Agent | -| ping | Pings a node to check if it is online | 1 | Agent-Agent | +| Command | Description | Level | Interaction | +|-------------|---------------------------------------|-------|-------------| +| add | Adds a node to the node graph | 1 | Local | +| connections | Lists all active node connections | 1 | Agent | +| claim | Makes a claim to a node | 1 | Agent-Agent | +| find | Attempts to find a node in the DHT | 1 | Agent-Agent | +| ping | Pings a node to check if it is online | 1 | Agent-Agent | +| getall | Gets all nodes from the node graph | 1 | Agent-Agent | ### Identities The identities subcommand allows control over the node's identity and its links with other social identities. -| Command | Description | Level | Interaction | -| ------------ | ------------------------------------------------------------------- | ----- | ----------- | -| claim | Claim an identity for this keynode | 1 | Local | -| authenticate | Authenticate a social identity provider (Github only) | 1 | Local | -| get | Gets the gestalt of a node or identity | 1 | Local | -| list | Lists the available gestalts | 1 | Local | -| trust | Trusts a node id or identity | 1 | Local | -| untrust | Untrusts a node id or identity | 1 | Local | -| search | Searches the provider for a connected identity | 1 | Local | -| allow | Set a specific permission for a Node or Identity | 2 | Local | -| disallow | Remove a Specific permission for a Node or Identity | 2 | Local | -| discover | Starts discovery process using Node or Identity as a starting point | 1 | Agent-Agent | -| perms | Gets the permisson for an node or identity | 1 | Local | +| Command | Description | Level | Interaction | +|---------------|---------------------------------------------------------------------|-------|-------------| +| claim | Claim an identity for this keynode | 1 | Local | +| authenticate | Authenticate a social identity provider (Github only) | 1 | Local | +| get | Gets the gestalt of a node or identity | 1 | Local | +| list | Lists the available gestalts | 1 | Local | +| trust | Trusts a node id or identity | 1 | Local | +| untrust | Untrusts a node id or identity | 1 | Local | +| search | Searches the provider for a connected identity | 1 | Local | +| allow | Set a specific permission for a node or an identity | 2 | Local | +| disallow | Remove a specific permission for a node or identity | 2 | Local | +| discover | Starts discovery process using node or identity as a starting point | 1 | Agent-Agent | +| permissions | Gets the permission for a node or an identity | 1 | Local | +| queue | Prints out vertices queued for discovery | 1 | Local | +| invite | Invites another keynode | 1 | Local | +| authenticated | Lists all authenticated identities across all providers | 1 | Local | ### Notifications | Command | Description | Level | Interaction | -| ------- | ----------------------------------------------- | ----- | ----------- | +|---------|-------------------------------------------------|-------|-------------| | send | Sends a notification to another node | 1 | Agent-Agent | | read | Displays notifications and marks them as "read" | 1 | Local | | clear | Clears all read and unread notifications | 1 | Local | @@ -139,10 +141,10 @@ The identities subcommand allows control over the node's identity and its links - Toggles should be `-f` `-v` flags that when used are `true` and when not used are `false`. These can be joined up together like `-fv`, but this may be confusing with the multiword options, and in which case I usually don't use the joined up versions. Flags should be sparing, users should not need to remember every flag they need to do something. - Options should ideally be optional `--key value` and `-k value`. In some cases they represent key-value parameters which are not optional. Make sure that multi-word options are like `--multi-word` and their short form is `-mw`. -- Parameters should be positional so `pk subcommand param1 param2`, in that case they are usually not optional and are required, it is possible to have arbitrary arity of parameters so you can have 1, or many. -- Exception is `pk subcommand -k value -k2 value -k3 value`, which is a key value parameters, this would not be optional, but in many cases if the commands are designed well, you should be able to have all values as parameters. +- Parameters should be positional so `polykey subcommand param1 param2`, in that case they are usually not optional and are required, it is possible to have arbitrary arity of parameters so you can have 1, or many. +- Exception is `polykey subcommand -k value -k2 value -k3 value`, which is a key value parameters, this would not be optional, but in many cases if the commands are designed well, you should be able to have all values as parameters. -Make sure you're using the output formatting functions in the `src/bin/utils.ts` (or at least that's where I had them last). This ensures you have a consistent set outputs, whether it is a list, table, json or otherwise. We can have `-f` to indicate different output formats for these. +Make sure you're using the output formatting functions in the `src/bin/utils.ts`. This ensures you have a consistent set outputs, whether it is a list, table, json or otherwise. We can have `-f` to indicate different output formats for these. And for testing, try to use the `main` exported function, but I think as you said on slack there are new methods that make it easier to test these that might have been created by @DrFacepalm or @scottmmorris. diff --git a/docs/reference/polykey-cli/commands/secrets.md b/docs/reference/polykey-cli/commands/secrets.md index b4a85649..eb0d27b5 100644 --- a/docs/reference/polykey-cli/commands/secrets.md +++ b/docs/reference/polykey-cli/commands/secrets.md @@ -2,86 +2,158 @@ ## `create` 1. Create a secret within a given vault -2. Requires a filepath as input which contains the secret +2. Requires a file path as input which contains the secret Usage: ```shell -> polykey secrets create /home/addievo/Desktop/Work/Polykey-CLI/random.txt vault1:secret1 +$ polykey secrets create ~/random.txt vault1:secret1 ``` -## `delete` -1. Deletes a secret from a specified vault +## `rm` +1. Removes one or more secrets from a specified vault +2. Ignores paths which do not exist and continues execution +3. Pass in the `-r` option to remove directories Usage: ```shell -> polykey secrets delete vault1:secret1 +$ polykey secrets rm vault1:secret1 -> polykey secrets get vault1:secret1 +$ polykey secrets cat vault1:secret1 +cat: secret1: No such file or directory +ErrorPolykeyCLICatSecret: Failed to concatenate one or more secrets -ErrorPolykeyRemote: Remote error from RPC call +$ polykey secrets rm vault1:abc vault1:xyz + +$ polykey secrets cat vault1:secret1 +cat: abc: No such file or directory +cat: xyz: No such file or directory +ErrorPolykeyCLICatSecret: Failed to concatenate one or more secrets + +$ polykey secrets rm vault1:file1 vault1:invalid vault1:file2 +rm: cannot remove 'invalid': No such file or directory +ErrorPolykeyCLIRemoveSecret: Failed to remove one or more secrets +# Files 'file1' and 'file2' have been removed + +$ polykey secrets rm vault1:dir1 +rm: cannot remove 'test': Is a directory +ErrorPolykeyCLIRemoveSecret: Failed to remove one or more secrets + +$ polykey secrets rm -r vault1:dir1 +# Command finishes successfully this time ``` ## `dir` -1. Adds a directory within a Given Vault +1. Adds a directory within a given vault 2. Requires dir to be added as a parameter 3. Requires the vault where to the dir is to be added Usage: ```shell -> polykey secrets dir /home/addievo/Desktop/Work/Polykey-CLI/random vault2 +$ polykey secrets dir ~/test-dir vault1 ``` -## `edit` -1. Edit a secret within a vault +## `ed` +1. Edit a secret within a vault by launching the preferred editor +2. If the secret doesn't exist, a new and empty secret is created for editing +3. If the edited file isn't saved or the editor crashes, the secret will not be written + +:::warning +This command does not work on Windows yet +::: Usage: ```shell -> polykey secrets create /home/addie/Desktop/Work/Polykey-CLI/random.txt vault2:secret2 -> polykey secrets edit vault2:secret2 -# This opens an editor window in your editor of choice, vim/nano/vsc -(node:121206) [DEP0147] DeprecationWarning: In future versions of Node.js, fs.rmdir(path, { recursive: true }) will be removed. Use fs.rm(path, { recursive: true }) instead -(Use `node --trace-deprecation ...` to show where the warning was created npm run polykey -- secrets get vault2:secret2 +$ polykey secrets ed vault1:secret2 +# This opens an editor window in your editor of choice, vim/nano/etc.. -> polykey secrets get vault2:secret2 - -Yo-THISISEDITED +$ polykey secrets cat vault1:secret2 +I edited this secret inside an editor ``` -## `get` -1. Fetches a secret from a specified vault +## `cat` +1. Fetches one or more secrets from a specified vault and concatenates them +2. Skips to the next argument if a secret encounters an error while reading +3. File contents are printed out to `stdout` and errors to `stderr` +4. If no paths are specified, this command takes input from `stdin` and prints it to `stdout` + +:::tip +`^D` in the terminal stands for the key combination 'Ctrl-D' +::: Usage: ```shell -> polykey secrets get vault2:secret2 - -Yo-THISISEDITED +$ polykey secrets cat vault1:secret2 +I edited this secret inside an editor + +$ polykey secrets cat vault1:secret2 vault1:secret3 +I edited this secret inside an editorThis was written using create, though + +$ polykey secrets cat vault1:secret2 vault1:invalid vault1:secret3 +I edited this secret inside an editor +cat: invalid: No such file or directory +This was written using create, though +ErrorPolykeyCLICatSecret: Failed to concatenate one or more secrets + +$ polykey secrets cat vault1:secret2 vault1:invalid vault1:secret3 2>/dev/null +I edited this secret inside an editorThis was written using create, though + +$ polykey secrets cat +abc +abc +123 +123 +abc^D^Dabc +^D ``` -## `list` -1. Lists all secrets inside a specified vault +## `ls` +1. Lists all secrets within a specific directory inside a specified vault Usage: ```shell -> polykey secrets list vault2 - - -random/random2 +$ polykey secrets ls vault1 +secret1 secret2 +secret3 +file1 +file2 +abc +xyz +dir1 + +$ polykey secrets ls vault1:dir1 +dir1/.hidden-file +dir1/nothing-to-see-here ``` ## `mkdir` 1. Creates an empty directory within a vault +2. Skips invalid operations +3. To make a nested directory, pass in the `-p` option Usage: ```shell -> polykey secrets mkdir vault2:thisIsTheNewDir +$ polykey secrets mkdir vault1:testdir + +$ polykey secrets mkdir vault1:dir123 vault1:dir456 + +$ polykey secrets mkdir vault1:dir-abc vault1:abc/def/ghi vault1:dir-def +mkdir: cannot create directory abc/def/ghi: No such file or directory + +$ polykey secrets mkdir -p vault1:abc/def/ghi + +$ polykey secrets ls vault1:abc +abc/def + +$ polykey secrets ls vault1:abc/def +abc/def/ghi ``` ## `rename` @@ -92,24 +164,28 @@ Usage: Usage: ```shell -> polykey secrets rename vault2:secret2 thisSecretHasBeenRenamed +$ polykey secrets ls vault1 +secret2 -> polykey secrets list vault2 +$ polykey secrets rename vault1:secret2 new-name -random/random2 -thisSecretHasBeenRenamed +$ polykey secrets ls vault1 +new-name ``` ## `stat` 1. Get the stats of a specified secret from a vault 2. Requires secret location (vaultName:secretName) as a parameter +:::note +The mode (or file permissions) doesn't exist within a vault +::: + Usage: ```shell -> polykey secrets stat vault2:thisSecretHasBeenRenamed - -Stats for "thisSecretHasBeenRenamed" +$ polykey secrets stat vault1:new-name +Stats for "new-name" dev: 0 ino: 1455 mode: 33188 @@ -123,19 +199,68 @@ mtime: Wed Dec 06 2023 13:50:07 GMT+1100 (Australian Eastern Daylight Time) ctime: Wed Dec 06 2023 13:56:52 GMT+1100 (Australian Eastern Daylight Time) birthtime: Wed Dec 06 2023 13:49:19 GMT+1100 (Australian Eastern Daylight Time) blksize: 4096 -blocks: +blocks: 1 ``` -## `update` -1. Update a secret +## `env` +1. Export one or multiple secrets within a vault as environment variables +2. Run a command with the specified variables, or export them in the current working environment -Usage: +:::note +Separate the environment variables from the command by passing in a `--` +::: +Usage: ```shell -> polykey secrets list vault2 +$ polykey secrets ls my-project +OPENAI_API_KEY +GOOGLE_MAPS_API_KEY +PROD_DB_PASSWORD + +$ polykey secrets env my-project:OPENAI_API_KEY +OPENAI_API_KEY='do not commit your keys to github' + +$ polykey secrets env my-project:OPENAI_API_KEY my-project:PROD_DB_PASSWORD +OPENAI_API_KEY='do not commit your keys to github' +PROD_DB_PASSWORD='password123abc' + +$ polykey secrets env my-project +OPENAI_API_KEY='do not commit your keys to github' +GOOGLE_MAPS_API_KEY='abc123' +PROD_DB_PASSWORD='password123abc' + +$ polykey secrets env my-project -- bash -c 'echo $OPENAI_API_KEY' +do not commit your keys to github + +$ echo $OPENAI_API_KEY +# It is not set in the current shell yet -random/random2 -thisSecretHasBeenRenamed +$ . <(polykey secrets env my-project) -> npm run polykey -- secrets update /home/addievo/Desktop/Work/Polykey-CLI/random.txt vault2:thisSecretHasBeenRenamed +$ echo $OPENAI_API_KEY +do not commit your keys to github +``` + +## `write` +1. Reads input from `stdin` and writes it to the specified file +2. If the file doesn't exist, it gets created + +:::tip +`stdin`, or standard input, can be either manually entered by typing, or piped in through another command. + +To close the input steam and save the file, press `^D`, or 'Ctrl-D' in a new line, or press `^D` twice on the same line. +::: + +Usage: + +```shell +$ polykey secrets write vault1:file +this will be entered into the file +testing123 +abc^D^D + +$ polykey secrets cat vault1:file +this will be entered into the file +testing123 +abc ``` diff --git a/docs/reference/polykey-cli/commands/vaults.md b/docs/reference/polykey-cli/commands/vaults.md index fa96c2f3..b282ec96 100644 --- a/docs/reference/polykey-cli/commands/vaults.md +++ b/docs/reference/polykey-cli/commands/vaults.md @@ -1,79 +1,75 @@ # `polykey vaults` ## `clone` -1. Clone a vault from another nodeID -2. Requires vaultName to be cloned as a parameter -3. Requires nodeID of the Node with access to the vault as a parameter +1. Clone a vault from another node ID +2. Requires vault name to be cloned as a parameter +3. Requires node ID of the node with access to the vault as a parameter Usage: ```shell -> polykey vaults clone vaultFromOtherNode v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 +$ polykey vaults clone newvault v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 -> polykey vaults list - -vault1 zS4cBAnYTa3221RYLPWT4q6 -vault2 zUUqm8tN22MkaR3zvMKnKQw -vaultFromOtherNode zMC3GPfmdx2XhXHN5Ra3tKT +$ polykey vaults list +vault zS4cBAnYTa3221RYLPWT4q6 +newvault zMC3GPfmdx2XhXHN5Ra3tKT ``` ## `create` -1. Create a new Vault -2. Requires vaultName as a parameter - +1. Create a new vault +2. Requires the vault name as a parameter Usage: ```shell -> polykey vaults create vault1 +$ polykey vaults create my-vault +Vault zMC3GPfmdx2XhXHN5Ra3tKT created successfully -Vault zS4cBAnYTa3221RYLPWT4q6 created successfully +$ polykey vaults list +vault zS4cBAnYTa3221RYLPWT4q6 +myvault zMC3GPfmdx2XhXHN5Ra3tKT ``` -## `delete` -1. Delete an existing Vault -2. Requires vaultName as a parameter +## `rm` +1. Delete an existing vault +2. Requires the vault name as a parameter Usage: ```shell -> polykey vaults list - -thisVaultWillBeDeleted zEFsW8znHjfL6Y57juQcxEw -vault1 zS4cBAnYTa3221RYLPWT4q6 +$ polykey vaults list +vault zS4cBAnYTa3221RYLPWT4q6 +delete-me zEFsW8znHjfL6Y57juQcxEw -> polykey vaults delete thisVaultWillBeDeleted +$ polykey vaults delete delete-me -> polykey vaults list - -vault1 zS4cBAnYTa3221RYLPWT4q6 +$ polykey vaults list +vault zS4cBAnYTa3221RYLPWT4q6 ``` -## `list` -1. Lists all currently available vaults +## `ls` +1. Lists all locally cloned vaults Usage: ```shell -> polykey vaults list - -vault1 zS4cBAnYTa3221RYLPWT4q6 -vault2 zUUqm8tN22MkaR3zvMKnKQw +$ polykey vaults list +vault zS4cBAnYTa3221RYLPWT4q6 ``` ## `log` -1. Get logs incl version history from a vault +1. Get logs (including the version history) from a vault +2. A version commit can be used to reset the vault state to that version Usage: ```shell -> polykey vaults log vault2 - +$ polykey vaults log vault commit 8a8937f23baf0195081a429b3ea34bb26d498028 committer vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00 Date: Wed Dec 06 2023 13:56:57 GMT+1100 (Australian Eastern Daylight Time) -secret2 deleted,thisSecretHasBeenRenamed added +secret2 deleted,renamedSecret added commit cc6a5ac11b14615d9f8d9d633a7f8ab41e0a366c committer vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00 @@ -102,62 +98,61 @@ Initial Commit Usage: ```shell -> polykey -np ./tmp/nodeA vaults permissions vaultFromOtherNode - +$ polykey vaults permissions newvault vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00: pull, clone ``` ## `pull` -1. Pull updated changes from a vault which is shared from another Node +1. Pull updated changes from a vault which is shared from another node Usage: ```shell -> polykey -np ./tmp/nodeA secrets create /home/addievo/Desktop/Work/> polykey-CLI/random.txt vaultFromOtherNode:secretFromOtherNode - -> polykey secrets list vaultFromOtherNode +# Specifying an alternate node path to simulate another node +$ polykey -np /tmp/nodeA secrets touch other-vault:other-secret -> polykey vaults pull vaultFromOtherNode +# Back to the original node +$ polykey secrets list other-vault -> polykey secrets list vaultFromOtherNode +$ polykey vaults pull other-vault -secretFromOtherNode +$ polykey secrets list other-vault +other-secret ``` ## `rename` -1. Rename an existing Vault +1. Rename an existing vault Usage: ```shell -> polykey vaults rename vault2 thisHasBeenRenmaed && > polykey -- vaults list +$ polykey vaults rename myvault renamedvault -thisHasBeenRenmaed zUUqm8tN22MkaR3zvMKnKQw -vault1 zS4cBAnYTa3221RYLPWT4q6 +$ polykey vaults list +vault zS4cBAnYTa3221RYLPWT4q6 +renamedvault zUUqm8tN22MkaR3zvMKnKQw ``` ## `scan` -1. Lists shared vaults from a specified nodeID +1. Scans for new shared vaults from a specified node ID Usage: ```shell -> polykey vaults scan v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 - -vaultFromOtherNode z2CtVYNDudjXQPPzdcSfSDa pull,clone +$ polykey vaults scan v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 +other-vault z2CtVYNDudjXQPPzdcSfSDa pull,clone ``` ## `share` -1. Share Vault with another Node, with their node ID +1. Share a vault with another node using their node ID Usage: ```shell -> polykey -np ./tmp/nodeA vaults share vaultFromOtherNode vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00 - -> polykey -np ./tmp/nodeA vaults permissions vaultFromOtherNode +$ polykey vaults share myvault v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 -vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00: pull, clone +$ polykey vaults permissions myvault +v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0: pull, clone ``` ## `unshare` @@ -166,45 +161,31 @@ vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00: pull, clone Usage: ```shell -> polykey -np ./tmp/nodeA vaults unshare vaultFromOtherNode vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00 +$ polykey vaults unshare myvault v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 ``` ## `version` -1. Set a vault to a previous or specific version +1. Set a vault to a previous or specific version obtained from the vault commit logs Usage: ```shell +$ polykey secrets list myvault +file1 -> polykey secrets list vaultFromOtherNode - -secretFromOtherNode - -> polykey vaults log vaultFromOtherNode - -commit 46ad871a2164effc00a9b2a1ba0591b0b3ba1883 -committer v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 -Date: Wed Dec 06 2023 14:25:42 GMT+1100 (Australian Eastern Daylight Time) -Merge branch 'HEAD' of http:// - +$ polykey vaults log myvault commit 9833f539314c278422ee7d7891929214f62c3c24 committer v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 Date: Wed Dec 06 2023 14:25:07 GMT+1100 (Australian Eastern Daylight Time) -secretFromOtherNode added +file1 added commit ca9a7cc7a680866022eff2d66ce2444862dd4a5e committer vctg4j8988mkobuvruaj2ijmij6jinvk8nf714f0s11kq3blc8g00 Date: Wed Dec 06 2023 14:22:52 GMT+1100 (Australian Eastern Daylight Time) Initial Commit -commit 4faa50023c14ad0dbc7bb6204a691d361234ea22 -committer v2ki21482dokemqrrrc9e3oqr3s43nh3t92cbjua2vks3aopt1vr0 -Date: Wed Dec 06 2023 14:18:24 GMT+1100 (Australian Eastern Daylight Time) -Initial Commit - -> polykey vaults version vaultFromOtherNode ca9a7cc7a680866022eff2d66ce2444862dd4a5e - -> polykey secrets list vaultFromOtherNode +$ polykey vaults version myvault ca9a7cc7a680866022eff2d66ce2444862dd4a5e -# Vault is cloned to state before secretFromOtherNode was pulled +$ polykey secrets list vaultFromOtherNode +# Vault is changed to a state before writing file1 ``` diff --git a/docs/tutorials/polykey-cli/installation.md b/docs/tutorials/polykey-cli/installation.md index f477832c..9248ba08 100644 --- a/docs/tutorials/polykey-cli/installation.md +++ b/docs/tutorials/polykey-cli/installation.md @@ -34,7 +34,7 @@ Download the executable named `...-polykey-cli-V.V.V-linux-x64`, and rename it t Make it executable: ```sh -chmod u+x ./polykey +$ chmod u+x ./polykey ``` ### Add it to your `$PATH`. @@ -42,8 +42,8 @@ chmod u+x ./polykey #### For ZSH: 1. `cd` into directory where polykey exec is stored. -2. Edit the zsh config to add polykey to your path, to streamline the process, run the following command making sure to change the path to polykey if the polykey executable is not in the downloads folder. -3. For most users, this would be `~/downloads` on Debian based systems. +2. Edit the zsh config to add polykey to your path. To streamline the process, run the following command, making sure to change the path to polykey if the polykey executable is not in the downloads folder. +3. For most users, this would be `~/Downloads` :::warning @@ -51,17 +51,19 @@ Make sure your path to the polykey executable is correct. ::: -```SH -echo 'export PATH=~/downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc +```sh +$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc ``` -You can now run it with `polykey`. +You only need to run this command once. After running this command, you can now invoke polykey by typing `polykey` into the terminal. --- #### For Bash: -1. If you're using Bash, run the following command to add polykey to your path. Ensure to change the path if the executable is not in the downloads folder. For most users, this would be `~/downloads` on Debian-based systems. +1. `cd` into directory where polykey exec is stored. +2. Edit the zsh config to add polykey to your path. To streamline the process, run the following command, making sure to change the path to polykey if the polykey executable is not in the downloads folder. +3. For most users, this would be `~/Downloads` :::warning @@ -70,35 +72,35 @@ Make sure your path to the polykey executable is correct. ::: ```sh -echo 'export PATH=~/downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc +$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc ``` -You can now run it with `polykey`. +You only need to run this command once. After running this command, you can now invoke polykey by typing `polykey` into the terminal. --- ### NixOS -We have not yet published a Nixpkgs expression for Polykey. When we do, you will be able to just install `polykey-cli` from Nixpkgs. +We have not yet published a Nix package for Polykey. When we do, you will be able to just install `polykey-cli` from Nixpkgs. -However it is easy enough to install it from source. +However, it is easy enough to install it from source. Clone the repository: ```sh -git clone https://github.com/MatrixAI/Polykey-CLI.git +$ git clone https://github.com/MatrixAI/Polykey-CLI.git ``` Enter the `nix-shell`: ```sh -nix-shell +$ nix-shell ``` Build the application and install it into the user profile: ```sh -nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)" +$ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)" ``` ### Other @@ -152,7 +154,7 @@ and MacOS permits running of unsigned binaries, however, to progress past this, #### Method #1 - quickest method -The xattr command will remove the quarantine attribute from the polykey executable, allowing you to run it without triggering macOS security warnings. Remember to ensure that the file path matches the location of your polykey file. +The `xattr` command will remove the quarantine attribute from the Polykey executable, allowing you to run it without triggering macOS security warnings. Remember to ensure that the file path matches the location of your polykey file. ```sh sudo xattr -r -d com.apple.quarantine ~/Downloads/polykey @@ -380,7 +382,7 @@ Install it with: npm install -g polykey-cli ``` -This will install the Polykey-CLI into `$(npm config get prefix)`. +This will install the Polykey-CLI into the path pointed to by the command `$(npm config get prefix)`. If the `npm` bin path is added to the `$PATH` environment variable, then you will be able to execute `pk` or `polykey`.