diff --git a/docs/tutorials/polykey-cli/README.md b/docs/Getting-Started/polykey-cli/README.md similarity index 90% rename from docs/tutorials/polykey-cli/README.md rename to docs/Getting-Started/polykey-cli/README.md index f2f6489b..068d98e1 100644 --- a/docs/tutorials/polykey-cli/README.md +++ b/docs/Getting-Started/polykey-cli/README.md @@ -30,24 +30,31 @@ The CLI is open-source and available on GitHub: Polykey is continuously built and tested on: -- Linux x64 / arm64 +- Linux x64 - MacOS x64 / arm64 - Windows x64 - Docker -:::note Polykey is currently in beta. Its interface is at various levels of -stability. So bear with us as we perfect its design. You can contribute by -discussing with us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue -tickets in the -[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). ::: +:::note Note + +Polykey is currently in beta. Its interface is at various levels of stability. +So bear with us as we perfect its design. You can contribute by discussing with +us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue tickets in the +[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). + +::: ## Getting Started Start your journey with Polykey by following the tutorials below in sequence: -:::tip For a visual walkthrough, check out our +:::tip Tip + +For a visual walkthrough, check out our [getting started demo video](https://vimeo.com/884649667) after installing -Polykey. ::: +Polykey. + +::: 1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install Polykey CLI on your platform. diff --git a/docs/tutorials/polykey-cli/bootstrapping.md b/docs/Getting-Started/polykey-cli/bootstrapping.md similarity index 84% rename from docs/tutorials/polykey-cli/bootstrapping.md rename to docs/Getting-Started/polykey-cli/bootstrapping.md index 44aeb7c8..acf35bea 100644 --- a/docs/tutorials/polykey-cli/bootstrapping.md +++ b/docs/Getting-Started/polykey-cli/bootstrapping.md @@ -24,8 +24,20 @@ encryption and decryption of all node state and secret data managed by Polykey. You will be prompted to provide a root password. This password encrypts the root key. -:::note Remember to keep your password in a secure location as you will need it -each time you start the Polykey agent. ::: +:::note Note + +Remember to keep your password in a secure location as you will need it each +time you start the Polykey agent. + +::: + +:::important + +Bootstrapping also returns a **recovery code**. This code is required to recover +a node with the same ID, so it is critical that you store it safely and +securely. If lost, node identity recovery will not be possible. + +::: ### Starting the Polykey Agent @@ -64,7 +76,8 @@ If the Polykey agent does not terminate properly, you can force quit the process through the Activity Monitor on your machine. If you encounter this or any other issue, please consider making a [bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) to help -improve Polykey. +improve Polykey. Please make sure to check for existing issues before creating a +new one. ## Check Agent Status @@ -80,19 +93,19 @@ including its connectivity and activity within the network. ### Example Output ```bash -status LIVE -pid 96992 +sstatus LIVE +pid 20004 nodeId vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg -clientHost ::1 -clientPort 54975 +clientHost 127.0.0.1 +clientPort 51980 agentHost :: -agentPort 60358 -upTime 8 -startTime 1716509093 -connectionsActive 3 -nodesTotal 11 -version 1.2.3-alpha.4-1-1 -sourceVersion 1.2.3-alpha.4 +agentPort 58078 +upTime 120 +startTime 1742186927 +connectionsActive 0 +nodesTotal 2 +version 1.21.4-1-1 +sourceVersion 1.21.4 stateVersion 1 networkVersion 1 ``` diff --git a/docs/tutorials/polykey-cli/claiming-digital-identities.md b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md similarity index 88% rename from docs/tutorials/polykey-cli/claiming-digital-identities.md rename to docs/Getting-Started/polykey-cli/claiming-digital-identities.md index 3a093a1c..3d72a986 100644 --- a/docs/tutorials/polykey-cli/claiming-digital-identities.md +++ b/docs/Getting-Started/polykey-cli/claiming-digital-identities.md @@ -1,4 +1,4 @@ -# Claiming Digital Identities: Establishing Identity Linkages in Polykey +# Establishing Identity Linkages In Polykey, claiming a digital identity is a crucial step that allows users to establish their identity across various platforms and link these identities to @@ -9,6 +9,8 @@ cryptographic link to a publicly verifiable location. This tutorial will guide you through the steps to authenticate with GitHub and claim an identity using Polykey, enhancing security and streamlining identity verification, making it easier for other users to discover and trust your nodes. +Currently, we only support github as an identity provider, but we plan to add +more in the future. ## Step 1: Authenticate with GitHub @@ -31,8 +33,10 @@ polykey identities authenticate ``: The identifier for the digital identity provider, such as "github". ::: -:::note Since Polykey currently only supports GitHub as an IdP, this is the -command that you will use to start the authentication process. +:::note Note + +Since Polykey currently only supports GitHub as an IdP, this is the command that +you will use to start the authentication process. ```bash polykey identities authenticate github @@ -72,19 +76,19 @@ identityId maverick During the authentication process, here's what Polykey requests access to and why: -- **Create Gists:** Polykey creates a gist under your GitHub account containing - a cryptographic link. This link is a verifiable method that proves the - ownership of your GitHub identity to anyone checking your Polykey gestalt +- **Currently: Create Gists:** Polykey creates a gist under your GitHub account + containing a cryptographic link. This link is a verifiable method that proves + the ownership of your GitHub identity to anyone checking your Polykey gestalt graph. -- **Read All User Profile Data:** This enables Polykey to access your profile - details, including your username, followers, and public repository data. This - information is used to ensure that the identity you claim corresponds - accurately to your public digital footprint, enhancing trust and verification. +-:::note Note + +**Future Plan: Read All User Profile Data:** This enables Polykey to access your +profile details, including your username, followers, and public repository data. +This information is used to ensure that the identity you claim corresponds +accurately to your public digital footprint, enhancing trust and verification. -- **Access User Email Addresses (read-only):** By accessing the email addresses - associated with your account, Polykey can better manage notifications related - to your secrets operations. +::: #### Security and Privacy Considerations @@ -150,6 +154,12 @@ This gist contains the cryptographic link confirming that your Polykey identity is correctly linked to your GitHub profile. Viewing this gist ensures your claim was successful and publicly verifiable. +:::note Note + +This information should not be modified or the claim might be invalidated. + +::: + ## Understanding Gestalt Graphs In Polykey, claiming identities creates a **gestalt graph**—a dynamic, diff --git a/docs/tutorials/polykey-cli/discovering-other-users.md b/docs/Getting-Started/polykey-cli/discovering-other-users.md similarity index 93% rename from docs/tutorials/polykey-cli/discovering-other-users.md rename to docs/Getting-Started/polykey-cli/discovering-other-users.md index abccd71d..aed997c7 100644 --- a/docs/tutorials/polykey-cli/discovering-other-users.md +++ b/docs/Getting-Started/polykey-cli/discovering-other-users.md @@ -39,9 +39,11 @@ polykey identities discover polykey identities discover github.com:maverick ``` -This command adds the node associated with the GitHub username "maverick" to -your discovery queue, allowing you to initiate interactions with this user. -:::note +:::note Note This command adds the node associated with the GitHub username +"maverick" to your discovery queue, allowing you to initiate interactions with +this user. + +::: ## Troubleshooting Discovery and Connection Issues @@ -77,8 +79,6 @@ network. ::: -:::info - ### Future Enhancements Polykey is actively working to enhance the discovery process by implementing @@ -116,12 +116,9 @@ Permissions in Polykey determine what actions a node or an identity can perform within the network. Here’s a general list of potential permissions that can be managed: -- **Read:** Allows viewing but not modifying. -- **Write:** Allows both viewing and modifying. -- **Execute:** Allows performing specific actions. +- **Scan:** Allows the node to scan for vaults - **Notify:** Allows sending notifications about changes or updates. -- **Trust:** Allows a node to be trusted, generally affecting how interactions - are secured. +- **Claim** Allows a different gstalt to claim the node #### Example Command to Set Permissions @@ -197,8 +194,8 @@ polykey identities list ### Trusting and Untrusting Nodes -You can explicitly trust or untrust a node to refine how notifications and -access controls are handled: +You can explicitly trust or untrust individual nodes or entire gestalts to +refine how notifications and access controls are handled: ```bash polykey identities trust diff --git a/docs/tutorials/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md similarity index 90% rename from docs/tutorials/polykey-cli/installation.md rename to docs/Getting-Started/polykey-cli/installation.md index adf69156..9802f831 100644 --- a/docs/tutorials/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -7,10 +7,16 @@ environment. :::info -Polykey-CLI has only been tested on Linux and macOS. We are working on -supporting other platforms. There's minor teething problems when it comes -supporting other platforms. Help us by reporting any issues with the CLI tool in -our Github Repo +## Polykey Core Overview + +The Polykey CLI and core primarily use TypeScript for service logic, domain +business operations, and persistence layers. While the main codebase is in +TypeScript, some supporting libraries incorporate native C++ or Rust for +platform‐specific functionality. This approach combines cross‐platform +convenience with native performance optimizations. Polykey-CLI has only been +tested on Linux and macOS. We are working on supporting other platforms. There's +minor teething problems when it comes supporting other platforms. Help us by +reporting any issues with the CLI tool in our Github Repo [here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping a message to the developers in our discord server [here](https://discord.gg/dC32r35TeE). @@ -126,15 +132,15 @@ $ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$( We will be working on other distribution methods. - + ## MacOS :::info -ARM-64 builds are not currently supported on MacOS as of **26-03-24.** However, -building Polykey yourself on MacOS resolves in a working binary. Follow this -guide below to manually build and install Polykey on macOS. +ARM-64 builds are not currently supported on MacOS as of **6 April 2025.** +However, building Polykey yourself on MacOS resolves in a working binary. Follow +this guide below to manually build and install Polykey on macOS. ::: @@ -284,13 +290,21 @@ echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc +:::tip + +The path export should not pint to the Polykey executable itself, but rather to +the directory containing the executable. Otherwise, the executable will not be +found and will not work. + +::: + #### For Bash: 1. `cd` into the directory where the "polykey" executable is stored. 2. Edit the Bash 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 executable is not in the downloads folder. For most users, - this would be `~/downloads` on Debian-based systems. + this would be `~/Downloads` :::tip @@ -408,7 +422,7 @@ docker run -it 0e1addd9855a agent start --background -np /tmp/polykey Making sure to replace `0e1addd9855a` with your corresponding image ID. ```shell - docker run -it 0e1addd9855a agent start --background -np /tmp/polykey +$ docker run -it 0e1addd9855a agent start --background -np /tmp/polykey WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested ✔ Enter new password … * ✔ Confirm new password … * @@ -418,7 +432,7 @@ clientHost 127.0.0.1 clientPort 45509 agentHost :: agentPort 37468 -recoveryCode net elephant gentle eight pulp oyster panther sing own autumn silly whip simple warfare daughter pepper detail bachelor awkward forget ignore cream silly raw +recoveryCode (random text recovery code goes here) ``` @@ -433,7 +447,7 @@ The CLI is published as Install it with: ```sh -npm install -g polykey-cli +npm install polykey ``` This will install the Polykey-CLI into the path pointed to by the command diff --git a/docs/tutorials/polykey-cli/managing-multiple-nodes.md b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md similarity index 96% rename from docs/tutorials/polykey-cli/managing-multiple-nodes.md rename to docs/Getting-Started/polykey-cli/managing-multiple-nodes.md index 4adc59fb..9b614cbd 100644 --- a/docs/tutorials/polykey-cli/managing-multiple-nodes.md +++ b/docs/Getting-Started/polykey-cli/managing-multiple-nodes.md @@ -41,8 +41,12 @@ node we are starting an agent for. If unsure of the syntax to use for command operations, adding the --help at the end of each subcommand provides useful context. -:::note If a node has not been created before, initializing the Polykey agent -for it will also initiate the bootstrap process. ::: +:::note Note + +If a node has not been created before, initializing the Polykey agent for it +will also initiate the bootstrap process. + +::: When working with multiple nodes, specifying the node path in each command can become cumbersome. To streamline this process in your terminal shell session, @@ -69,7 +73,7 @@ specify a node path, so it automatically targets the default node path. **Shell B (for your new node, nodeB):** ```bash -polykey agent super_start --node-path ./nodeB --background +polykey agent start --node-path ./nodeB --background ``` This command starts a new Polykey agent for nodeB in the background. The first diff --git a/docs/tutorials/polykey-cli/managing-secrets.md b/docs/Getting-Started/polykey-cli/managing-secrets.md similarity index 56% rename from docs/tutorials/polykey-cli/managing-secrets.md rename to docs/Getting-Started/polykey-cli/managing-secrets.md index be040353..443d04e1 100644 --- a/docs/tutorials/polykey-cli/managing-secrets.md +++ b/docs/Getting-Started/polykey-cli/managing-secrets.md @@ -7,15 +7,17 @@ such as API keys, configuration files, or documents. These can be any file type that you need to encrypt and manage securely. This section provides a detailed guide on how to manage these secrets within vaults using Polykey-CLI. -:::tip +:::tip Tip In the Polykey CLI, you can get help with managing your Secrets Operations by -using the `-h` help command to get a detailed list of availiable options and -commands. Try running `polykey secrets -h` ::: +using the `--help` help command to get a detailed list of availiable options and +commands. Try running `polykey secrets --help` + +::: ## Creating Secrets -:::note +:::note Note **Create a Secret within a given Vault** @@ -28,7 +30,9 @@ secret. **secretPath:** Path to the secret to be created, -specified as `:` ::: +specified as `:` + +::: ### Adding a Secret to a Vault @@ -36,11 +40,15 @@ The `polykey secrets create` command clones an existing file from your local machine and stores it into an encrypted vault, creating a secret in the process. Thus, providing secure data-at-rest encryption of the file. -:::tip To create a secret, both the vault and file you are creating a secret -from, must already exist. Remember that to view the vaults contained within a -node, you run `$polykey vaults list`. This is useful for viewing the names of -the vaults you are trying to manage secrets with, as vaultName is one of the -command arguments that is commonly used. ::: +:::tip Tip + +To create a secret, both the vault and file you are creating a secret from, must +already exist. Remember that to view the vaults contained within a node, you run +`polykey vaults list`. This is useful for viewing the names of the vaults you +are trying to manage secrets with, as vaultName is one of the command arguments +that is commonly used. + +::: #### Command Arguments @@ -48,15 +56,15 @@ command arguments that is commonly used. ::: polykey secrets create : ``` - +:::info Info -:::info The `` for the file you are trying to create a secret from can -either be a working directory filepath or a root path. Also notice that we -either have 1 space of seperation or a `:` between command arguments usually. -The angle braces are just being used in our explanation for specifying the -arguments more clearly. ::: +The `` for the file you are trying to create a secret from can either +be a working directory filepath or a root path. Also notice that we either have +1 space of seperation or a `:` between command arguments usually. -#### Example Usage of `Polykey Secrets Create` +::: + +#### Example usage ```bash polykey secrets create ./API_ACCESS_KEY.txt my-api-vault:API_ACCESS_KEY @@ -68,16 +76,22 @@ secretName alias as `API_ACCESS_KEY`. We could have also provided the secretName alias as `API.ACCESS_KEY.txt` but for most text files in Polykey, specifying the file type extension is redundant. -:::tip Since the secret or `` stored in the vault does not specify -the file type in its metadata, when you are storing binary files such as images -or videos, you may want to specify the file extension in the `secretName` alias -for better access & manageability. ::: +:::tip Tip + +Since the secret or `` stored in the vault does not specify the file +type in its metadata, when you are storing binary files such as images or +videos, you may want to specify the file extension in the `secretName` alias for +better access & manageability. + +::: ## Listing Secrets -:::note **List all Available Secrets for a Vault** +:::note Note -**Usage:** `polykey secrets list|ls [options] ` +**List all Available Secrets for a Vault** + +**Usage:** `polykey secrets ls|list [options] ` **Arguments:** @@ -88,34 +102,29 @@ for better access & manageability. ::: To list the secret file(s) stored within a specific vault in your default nodePath, use: -#### Command Arguments: +### Command Arguments: ```bash -polykey secrets list +polykey secrets ls ``` #### Example Usage -```bash -Polykey secrets list my-api-vault -``` - -#### Example Output - In this case, there's just one secret file contained in this vault, the secret we created in the previous example. ```bash +$ polykey secrets ls my-api-vault API_ACCESS_KEY ``` -:::note - -### Secure Deletion of Local Secrets +:::tip Secure Deletion of Local Secrets After adding a secret to a vault, securely delete the local copy if it's no longer needed. This ensures that no unsecured traces of sensitive information -remain on your local filesystem. ::: +remain on your local filesystem. + +::: ## Retreiving Secrets @@ -123,11 +132,11 @@ Retrieve a secret from the given vault using the polykey secrets get command. This command accesses the encrypted content within a vault and outputs it, allowing for further handling depending on the file type. -:::note +:::note Note -Retrieve a Secret from the Given Vault +Retrieve a secret from the given vault -**Usage:** `polykey secrets get [options] ` +**Usage:** `polykey secrets cat [options] ` **Arguments:** @@ -149,33 +158,28 @@ The nature of the file affects how it is handled when retrieved: are binary files. These do not display readable content directly in the terminal and must be handled differently. -### Retrieving a Text File +### Retrieving a text file To view the contents of a text file stored in a vault directly from the terminal, use the following command: ```bash -polykey secrets get : +polykey secrets cat : ``` -#### Example: Retrieving a Text File - -Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault-tutorial-1` +#### Example -```bash -polykey secrets get my-vault-tutorial-1:API_ACCESS_KEY -``` +Retrieve the contents of the `API_ACCESS_KEY` stored in `my-vault` -#### Example Output - -```bash +```shell +$ polykey secrets cat my-vault:API_ACCESS_KEY AKfjd39jdi3903KDje93j04j0 ``` This method displays text files directly in the terminal, providing immediate access to the contents. -### Retrieving Binary File +### Retrieving a binary file Binary files, such as images or executables, need to be handled appropriately to view or use their contents correctly. @@ -186,29 +190,35 @@ To retrieve and handle a binary file, specify the output format by redirecting the output to a file with the appropriate file extension: ```bash -polykey secrets get : > . - +polykey secrets cat : > . ``` This command saves the binary content into a file in the current local directory, preserving the file type as indicated by the extension ``. -#### Example: Retrieving and Viewing an Image +#### Example Retrieve an image stored in a vault and view it using system-specific commands: ```bash -polykey secrets get my-NFT:Dali.png > Dali.png -open Dali.png +$ polykey secrets cat my-NFT:Dali.png > Dali.png +$ open Dali.png ``` -:::note The use of `>` in the command line is a standard Unix redirection -operator, used here to direct the output from Polykey into a file. This -operation is necessary for handling binary files that require specific -applications to open. ::: +:::note Note + +The use of `>` in the command line is a standard Unix redirection operator, used +here to direct the output from Polykey into a file. This operation is necessary +for handling binary files that require specific applications to open. -:::tip Ensure the secret name includes the file extension (like Dali.png), which -helps clarify the file type when saving and accessing the retrieved file. ::: +::: + +:::tip Tip + +Ensure the secret name includes the file extension (like Dali.png), which helps +clarify the file type when saving and accessing the retrieved file. + +::: ## Creating a Directory of Secrets @@ -220,7 +230,7 @@ vault. polykey secrets mkdir : ``` -#### Example: Creating a Directory in a Vault +### Example To create a directory named "NFTs" within the "my-image-vault": @@ -237,7 +247,7 @@ similar types of secrets under a common directory. polykey secrets create :/ ``` -#### Example: Adding a Secret to a Directory +#### Example To add the file "Dali.png" as a secret named "Dali.png" to the "NFTs" directory within "my-image-vault": @@ -246,20 +256,19 @@ within "my-image-vault": polykey secrets create ./Dali.png my-image-vault:NFTs/Dali.png ``` -:::note To view secrets saved within a directory in a vault, using the -`polykey secrets list ` command for that vault will output all -secrets in the vault, including those within directories. - -**Example Usage** +:::note Note -```bash - polykey secrets list my-image-vault -``` +To view secrets saved within a directory in a vault, using the +`polykey secrets ls ` command for that vault will output all secrets +in the directory, _not_ the entire vault. -**Output** +**Example Usage** ```bash -NFTs/Owner.png +$ polykey secrets ls my-image-vault +NFTs/ +$ polykey secrets ls my-image-vault:NFTs +NFTs/Dali.png ``` ::: @@ -272,26 +281,34 @@ To rename an existing secret: polykey secrets rename : ``` -:::tip Use the `secrets list` command to check on your renamed secretFile. ::: +:::tip Tip + +Use the `secrets ls` command to check on your renamed secretFile. + +::: ## Updating a Secret To update the contents of an existing secret: ```bash -polykey secrets update : +polykey secrets write : ``` -#### Example: Secrets Update +### Example ```bash -polykey secrets update ./rare-dali.png my-image-vault:NFTs/Dali.png +$ cat ./rare-dali.png | polykey secrets write my-image-vault:nfts/dali.png ``` -:::info This is essentially replacing the file content of an existing secret -while preserving the identity of the secret. One way to verify that the update -was performed sucesfully is by viewing the mtime (modified time) timestamp from -the `secrets stat` command. ::: +:::info Info + +This is essentially replacing the file content of an existing secret while +preserving the identity of the secret. One way to verify that the update was +performed sucesfully is by viewing the mtime (modified time) timestamp from the +`secrets stat` command. + +::: ## Retrieving Secret Metadata @@ -301,24 +318,33 @@ To view metadata about a secret: polykey secrets stat : ``` -#### Example: Viewing Metadata for a Secret +### Example ```bash polykey secrets stat my-image-vault:NFTs/Dali.png ``` -#### Example Output - -```yaml -dev 0 ino 158 mode 33188 nlink 1 uid 0 gid 0 -rdev 0 size 23450 atime Sat May 25 2024 17:22:34 GMT-0600 -mtime Sat May 25 2024 17:22:33 GMT-0600 ctime Sat May 25 2024 17:22:33 -GMT-0600 birthtime Fri May 24 2024 22:42:43 GMT-0600 blksize 4096 blocks 6 +```bash +$ polykey secrets stat myvault:file +dev 0 +ino 124 +mode 16877 +nlink 2 +uid 0 +gid 0 +rdev 0 +size 0 +atime Fri Aug 16 2024 16:55:58 GMT+1000 (Australian Eastern Standard Time) +mtime Mon Aug 19 2024 12:21:30 GMT+1000 (Australian Eastern Standard Time) +ctime Mon Aug 19 2024 12:21:30 GMT+1000 (Australian Eastern Standard Time) +birthtime Fri Aug 16 2024 16:55:58 GMT+1000 (Australian Eastern Standard Time) +blksize 0 +blocks 0 ``` :::note -### Understanding Metadata Terms +**Understanding Metadata Terms** - **dev:** Device number on which the file resides. - **ino:** File's inode number. @@ -342,48 +368,32 @@ GMT-0600 birthtime Fri May 24 2024 22:42:43 GMT-0600 blksize 4096 blocks 6 To remove a secret from a vault: ```bash -polykey secrets delete : -``` - -#### Example: Deleting a Secret - -```bash -polykey secrets list my-image-vault +polykey secrets rm : ``` -**Output:** +### Example ```bash -NFTs/Dali.png -THE_THIEF.png +$ polykey secrets ls my-image-vault:nfts +nfts/dali.png +nfts/some-image.png +$ polykey secrets rm my-image-vault:nfts/some-image.png +# Note the lack of output +$ polykey secrets ls my-image-vault:nfts +nfts/dali.png ``` -```bash -polykey secrets delete my-image-vault:THE_THIEF.png -``` +## Editing Secrets -Successful deletion does not produce output. Verify the secret was removed by -listing secrets in the vault. +To edit a secret directly within a vault using Polykey: ```bash -polykey secrets list my-image vault -``` - -**Output:** - -Notice that we have sucesfully removed one of the secrets from the vault now. - -```bash -NFTs/Dali.png +polykey secrets edit : ``` -## Editing Secrets in a Vault - -To edit a secret directly within a Vault using Polykey: +:::warning Warning -```bash -polykey secrets edit : -``` +The command `polykey secrets edit` on MacOS has a bug that we are investigating. +Use `polykey secrets update` in the meantime. -:::warning Polykey Secrets Edit on Mac OS has a bug that we are investigating. -Use Polykey Secrets Update in the meantime. ::: +::: diff --git a/docs/tutorials/polykey-cli/managing-vaults.md b/docs/Getting-Started/polykey-cli/managing-vaults.md similarity index 98% rename from docs/tutorials/polykey-cli/managing-vaults.md rename to docs/Getting-Started/polykey-cli/managing-vaults.md index f380be56..3d02cc01 100644 --- a/docs/tutorials/polykey-cli/managing-vaults.md +++ b/docs/Getting-Started/polykey-cli/managing-vaults.md @@ -55,17 +55,19 @@ If you need to remove a vault, you can delete it using the delete command: polykey vaults delete ``` -#### Example +:::note Example Delete the vault named myvault: ```bash -polykey vaults delete myvault +polykey vaults rm myvault ``` This operation does not produce output on successful execution, indicating the vault has been removed. +:::note + ## Viewing Vault History Each vault maintains a version history which tracks changes over time. Use the diff --git a/docs/tutorials/polykey-cli/sharing-vaults.md b/docs/Getting-Started/polykey-cli/sharing-vaults.md similarity index 97% rename from docs/tutorials/polykey-cli/sharing-vaults.md rename to docs/Getting-Started/polykey-cli/sharing-vaults.md index 335a27bd..224cb234 100644 --- a/docs/tutorials/polykey-cli/sharing-vaults.md +++ b/docs/Getting-Started/polykey-cli/sharing-vaults.md @@ -73,7 +73,7 @@ polykey vaults scan - ``: The Node ID of the node that shared the vault with you. -#### Example +:::note Example ```bash polykey vaults scan v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 @@ -81,6 +81,8 @@ polykey vaults scan v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 This command lists the vaults shared by the specified node. +:::note + ## Cloning the Shared Vault After identifying the shared vaults, the recipient can clone the desired vault @@ -93,12 +95,14 @@ polykey vaults clone - ``: The name of the vault to be cloned. - ``: The Node ID from which to clone the vault. -### Example +:::note Example ```bash polykey vaults clone myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 ``` +:::note + This command clones "myvault" from the specified node to the local system. ## Synchronizing Changes @@ -114,7 +118,7 @@ polykey vaults pull - ``: The name or ID of the vault to update. - ``: (Optional) The node ID from which to pull updates. -### Example +:::note Example ```bash polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500 @@ -122,7 +126,9 @@ polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv50 This command updates "myvault" with the latest changes from the specified node. -## Conclussion +:::note + +## Conclusion Sharing and synchronizing vaults in Polykey enhances collaboration and security across the network. By following these guidelines, users can effectively manage diff --git a/docs/tutorials/polykey-cli/using-environment-variables.md b/docs/Getting-Started/polykey-cli/using-environment-variables.md similarity index 92% rename from docs/tutorials/polykey-cli/using-environment-variables.md rename to docs/Getting-Started/polykey-cli/using-environment-variables.md index 536bc7d1..0ad7ffac 100644 --- a/docs/tutorials/polykey-cli/using-environment-variables.md +++ b/docs/Getting-Started/polykey-cli/using-environment-variables.md @@ -1,4 +1,4 @@ -# Using Environment Variables with Polykey +# Using Environment Variables Polykey revolutionizes the management of environment variables by injecting them securely into applications, surpassing traditional `.env` file methods. This @@ -45,7 +45,7 @@ critical use case for the polykey secrets env command. #### Example: Start an application with a secure API key ```bash -polykey secrets env --env Weather-Ops:API_KEY -- node app.js +polykey secrets env weather-ops:API_KEY -- node app.js ``` This will execute `app.js` with the `API_KEY` set, sourced from the @@ -59,13 +59,19 @@ application, you can output them in different formats. #### Unix-like Systems Example ```bash -polykey secrets env --env-format unix --env Weather-Ops:API_KEY +polykey secrets env --env-format unix --env MyVault:API_KEY + +API_KEY=someRandomValue123 ``` #### JSON Format Example ```bash -polykey secrets env --env-format json --env Weather-Ops:API_KEY +polykey secrets env --env-format json --env MyVault:API_KEY + +{ + "API_KEY": "someRandomValue123" +} ``` These commands display the environment variables in the console, useful for @@ -99,7 +105,8 @@ secrets. #### AWS CLI Integration Example ```bash -polykey secrets env --env AWS-Creds:AWS_ACCESS_KEY_ID,AWS-Creds:AWS_SECRET_ACCESS_KEY -- aws s3 ls +polykey secrets env \ + $ polykey secrets env aws-creds:AWS_ACCESS_KEY_ID aws-creds:AWS_SECRET_ACCESS_KEY -- aws s3 ls ``` This securely passes AWS credentials to the AWS CLI. @@ -125,7 +132,7 @@ management of environment variables. It allows for the dynamic and secure handling of sensitive data across different stages of development and deployment. -## Additional References +:::note Additional References We encourage you to delve deeper into Polykey and consider integrating it into your workflows. For further insights and to participate in community @@ -137,6 +144,8 @@ discussions, please explore the following resources: - [Using Polykey for secure access to cloud providers:](https://polykey.com/blog/introducing-a-new-standard-in-environment-secrets-management-with-polykey) Learn how Polykey facilitates secure interactions with cloud services. +:::note + ## Tying It All Together **1. Initial Setup by User A:** diff --git a/docs/README.md b/docs/README.md index 86d20745..fc2fda84 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,9 +7,6 @@ displayed_sidebar: docs Welcome to the Polykey documentation. -The documentation is structured using -[Divio system](https://documentation.divio.com/). - - [Tutorials](./tutorials) - these are a series of steps to introduce Polykey to new beginners to achieve a practical outcome - [How-To Guides](/docs/how-to-guides) - these are short guides on how to @@ -19,14 +16,12 @@ The documentation is structured using - [Reference](./reference/) - these are useful when you need remember how to use a particular command or function - - ## Introduction Polykey helps yourself, teams and software agents to manage and share secrets in a secure and easy-to-use manner. -- Usable for average humans, you don't need to be a cryptography or +- Usable for the average person, you don't need to be a cryptography or cybersecurity expert to securely manage and share secrets. - Can be integrated into software for automation of secret workflows. - Unifies the workflow between interactive password management and @@ -76,24 +71,24 @@ passwords or keys. For this reason, we think of secrets as "capabilities". -All secrets put into vaults. Each vault is a persistent fully-encrypted virtual -filesystem with automatic version history. Vaults can be shared with other -Polykey agents. +All secrets are put into vaults. Each vault is a persistent, fully encrypted +virtual filesystem with automatic version history. Vaults can be shared with +other Polykey agents. -Polykey's secrets management concept provides users with secure communication -and secure computation. +Polykey's secrets management system provides users with secure communication and +secure computation. ### Decentralized Trust -Sharing secrets depends secure communications. Secure communications depends on -trusted identities. +Sharing secrets depends on secure communications. Secure communications depends +on trusted identities. -Polykey introduced a concept called "Gestalt Identity". +Polykey introduces a concept called "Gestalt Identity". -A Gestalt Identity is a collection of digital identities (social media profiles -and Polykey nodes) that all represent the same entity. +A Gestalt Identity is a collection of digital identities (i.e. social media +profiles and Polykey nodes) that all represent the same entity. -When you start a Polykey agent, it immediate forms its own gestalt with the +When you start a Polykey agent, it immediately forms its own gestalt with the Polykey node as its only identity. Link up your digital identities to the node in order to expand your gestalt. diff --git a/docs/reference/polykey-cli/commands/secrets.md b/docs/reference/polykey-cli/commands/secrets.md index 5330a665..2594e06e 100644 --- a/docs/reference/polykey-cli/commands/secrets.md +++ b/docs/reference/polykey-cli/commands/secrets.md @@ -65,7 +65,11 @@ $ polykey secrets dir ~/test-dir vault1 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 ::: +:::warning Warning + +This command does not work on Windows yet + +::: Usage: @@ -85,7 +89,11 @@ I edited this secret inside an editor 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' ::: +:::tip Tip + +`^D` in the terminal stands for the key combination 'Ctrl-D' + +::: Usage: @@ -184,7 +192,11 @@ new-name 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 ::: +:::note Note + +The mode (or file permissions) doesn't exist within a vault + +::: Usage: @@ -213,7 +225,10 @@ blocks: 1 2. Run a command with the specified variables, or export them in the current working environment -:::note Separate the environment variables from the command by passing in a `--` +:::note Note + +Separate the environment variables from the command by passing in a `--` + ::: Usage: @@ -253,11 +268,15 @@ do not commit your keys to github 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. +:::tip 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. ::: +line, or press `^D` twice on the same line. + +::: Usage: diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md deleted file mode 100644 index 70771834..00000000 --- a/docs/tutorials/README.md +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Tutorials - -The tutorials here are recommended as an introduction to the Polykey ecosystem. - -They allow you to get started using Polykey in a practical manner. - -Each tutorial is categorized under a particular subproject. - - diff --git a/docs/tutorials/polykey-core/README.md b/docs/tutorials/polykey-core/README.md deleted file mode 100644 index d218cebf..00000000 --- a/docs/tutorials/polykey-core/README.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Core - - diff --git a/docs/tutorials/polykey-core/installation.md b/docs/tutorials/polykey-core/installation.md deleted file mode 100644 index 6e898ecc..00000000 --- a/docs/tutorials/polykey-core/installation.md +++ /dev/null @@ -1,118 +0,0 @@ -# Installation - -## Polykey Core - -The Polykey core contains the service, domain business logic and persistence -layers of Polykey. - -It is written in TypeScript and C++. - -The codebase is intended to be cross-platform, however it is currently only -tested on Linux. - -As a contributor, this would be your entrypoint to Polykey. - -:::caution - -At this point in time, the Polykey core library also contains all of the CLI -code. This means in order to use Polykey, you must use the Polykey core library. -We intend to extract out the CLI code, and move it into -[Polykey CLI](https://github.com/MatrixAI/Polykey-CLI). Once this is done, users -will not directly interact with the -[Polykey Core](https://github.com/MatrixAI/Polykey). Instead the core will just -be a dependency of the other projects. - -::: - -### Requirements - -- 64-bit Linux Operating System -- Node v16.15 or above and Node Package Manager -- Optionally `nix-shell` to setup development environment - -### Source Repository - -The official source repository is on GitHub. There is an additional mirror on -GitLab. - -```shell -git clone https://github.com/MatrixAI/Polykey.git -``` - -Use `npm install` to setup the project. - -:::tip - -If you have `nix-shell` available, enter into `nix-shell` and it will -automatically setup the develoment environment. - -::: - -### Node Package Manager - -The core library is published as -[`npm` package](https://www.npmjs.com/package/polykey). - -#### Global Package - -Install it with: - -```shell -npm install --location=global polykey -``` - -This will install the Polykey core library into `$(npm config get prefix)`. - -There will be 2 executables made available inside -`$(npm bin --location=global)`. - -For example on Ubuntu: - -```shell-session -$ tree "$(npm bin --location=global)" -/usr/local/bin/ -├── pk -> ../lib/node_modules/polykey/dist/bin/polykey.js -└── polykey -> ../lib/node_modules/polykey/dist/bin/polykey.js -``` - -If the `npm` bin path is added to the `$PATH` environment variable, then you -will be able to execute `pk` or `polykey`. - -#### Local Package - -Local installation is intended for downstream projects, where Polykey is -embedded as a JavaScript library. - -```shell -npm install polykey -``` - -Use the `npx polykey` or `npx pk` execute the local executables that are placed -in: - -```shell-session -$ tree ./node_modules/.bin -./node_modules/.bin/ -├── pk -> ../polykey/dist/bin/polykey.js -└── polykey -> ../polykey/dist/bin/polykey.js -``` - -### Bundled Executables - -The core library is also released as a bundled executable. This is intended for -users who do not have Node.js installed. - -Go to https://github.com/MatrixAI/Polykey/releases and download the relevant -asset. - -We currently bundle for these platforms: - -- linux-x64 - this should work for any Linux distribution that follows the - Filesystem Hierarchy Standard. -- win-x64 -- macos-x64 -- macos-arm64 - -:::caution - -Not all platfoms are supported currently. We have only tested on linux-x64. diff --git a/docs/tutorials/polykey-desktop/README.md b/docs/tutorials/polykey-desktop/README.md deleted file mode 100644 index b25b9fdd..00000000 --- a/docs/tutorials/polykey-desktop/README.md +++ /dev/null @@ -1,12 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Desktop - -[Polykey Desktop](https://github.com/MatrixAI/Polykey-Desktop) is the desktop -application providing a graphical user interface for interacting with the -Polykey network. It is still currently under development. As of now, there are -no tutorials for Polykey Desktop. - -Follow our development on [GitHub](https://github.com/MatrixAI/Polykey-Desktop). - - diff --git a/docs/tutorials/polykey-mobile/README.md b/docs/tutorials/polykey-mobile/README.md deleted file mode 100644 index 236e46a7..00000000 --- a/docs/tutorials/polykey-mobile/README.md +++ /dev/null @@ -1,12 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Polykey Mobile - -[Polykey Mobile](https://github.com/MatrixAI/Polykey-Mobile) is the mobile -application providing a graphical user interface for managing interactions with -the Polykey network from your mobile device. It is still currently under -development. As of now, there are no tutorials for Polykey Mobile. - -Follow our development on [GitHub](https://github.com/MatrixAI/Polykey-Mobile). - - diff --git a/sidebars.ts b/sidebars.ts index 1c9fb799..a53815df 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -4,59 +4,28 @@ const sidebars: SidebarsConfig = { docs: [ { type: 'category', - label: 'Tutorials', + label: 'Getting Started', collapsed: false, - link: { - type: 'doc', - id: 'tutorials/README', - }, items: [ { type: 'category', label: 'Polykey CLI', link: { type: 'doc', - id: 'tutorials/polykey-cli/README', + id: 'Getting-Started/polykey-cli/README', }, items: [ - 'tutorials/polykey-cli/installation', - 'tutorials/polykey-cli/bootstrapping', - 'tutorials/polykey-cli/managing-vaults', - 'tutorials/polykey-cli/managing-secrets', - 'tutorials/polykey-cli/claiming-digital-identities', - 'tutorials/polykey-cli/discovering-other-users', - 'tutorials/polykey-cli/sharing-vaults', - 'tutorials/polykey-cli/managing-multiple-nodes', - 'tutorials/polykey-cli/using-environment-variables', + 'Getting-Started/polykey-cli/installation', + 'Getting-Started/polykey-cli/bootstrapping', + 'Getting-Started/polykey-cli/managing-vaults', + 'Getting-Started/polykey-cli/managing-secrets', + 'Getting-Started/polykey-cli/claiming-digital-identities', + 'Getting-Started/polykey-cli/discovering-other-users', + 'Getting-Started/polykey-cli/sharing-vaults', + 'Getting-Started/polykey-cli/managing-multiple-nodes', + 'Getting-Started/polykey-cli/using-environment-variables', ], - }, - { - type: 'category', - label: 'Polykey Desktop', - link: { - type: 'doc', - id: 'tutorials/polykey-desktop/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Mobile', - link: { - type: 'doc', - id: 'tutorials/polykey-mobile/README', - }, - items: [], - }, - { - type: 'category', - label: 'Polykey Core', - link: { - type: 'doc', - id: 'tutorials/polykey-core/README', - }, - items: ['tutorials/polykey-core/installation'], - }, + }, ], }, {