From e38da817d0258742e5578defcc37266fdbc0eec0 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 4 May 2025 17:28:37 -0600 Subject: [PATCH 01/16] docs: add Linux CLI terminal installation instructions and clean up outdated steps --- .../polykey-cli/installation.md | 63 +++++-------------- 1 file changed, 14 insertions(+), 49 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 9802f831..a546ecc8 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -42,64 +42,29 @@ libraries that Node.js requires. ### Manually -Builds for Linux is released on GitHub: -https://github.com/MatrixAI/Polykey-CLI/releases. - -Download the executable named `...-polykey-cli-V.V.V-linux-x64`, and rename it -to `polykey`. - -Make it executable: - -```sh -$ chmod u+x ./polykey -``` - -### Add it to your `$PATH`. - -#### 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` - -:::warning - -Make sure your path to the polykey executable is correct. +#### Using the Polykey CLI via the terminal -::: - -```sh -$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.zshrc && source ~/.zshrc -``` - -You only need to run this command once. After running this command, you can now -invoke polykey by typing `polykey` into the terminal. - ---- +If you prefer not to use a package manager or Docker, you can install Polykey directly via the terminal using a prebuilt binary. -#### For Bash: +1. Download the executable from the [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases) and rename it to `polykey`. -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` +2. Make it executable: -:::warning + ```sh + chmod u+x ./polykey -Make sure your path to the polykey executable is correct. +3. Move it into a directory in your $PATH, or add the current directory to your $PATH temporarily: +* For ZSH: -::: + echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc -```sh -$ echo 'export PATH=~/Downloads/polykey:$PATH' >> ~/.bashrc && source ~/.bashrc -``` +* For Bash: + echo 'export PATH=~/Downloads:$PATH' >> ~/.bashrc && source ~/.bashrc -You only need to run this command once. After running this command, you can now -invoke polykey by typing `polykey` into the terminal. +4. Confirm the installation: + polykey --version +If it returns the version, you’re ready to use the CLI. --- ### NixOS From 438be4a8e6ea637d39c195cc330c60acad76e8ed Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Tue, 6 May 2025 21:53:26 -0600 Subject: [PATCH 02/16] docs: adding info to force checks --- docs/Getting-Started/polykey-cli/installation.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index a546ecc8..5cea4ea2 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -1,4 +1,6 @@ -import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Admonition from '@theme/Admonition'; # Installation @@ -65,7 +67,15 @@ If you prefer not to use a package manager or Docker, you can install Polykey di polykey --version If it returns the version, you’re ready to use the CLI. ---- + + :::tip Important: Agent behavior + +Once you start the Polykey agent, the terminal window will be fully occupied by the running agent process. + +To continue issuing Polykey commands (e.g., to create a vault), you must open a **new terminal window**. +If the system shuts down or the agent process stops, you’ll need to **restart the agent** before running any other commands. + +::: ### NixOS From 4f8b075aed414416c8d5aa1503f9a624abd33f64 Mon Sep 17 00:00:00 2001 From: Aryan Jassal Date: Wed, 7 May 2025 13:58:20 +1000 Subject: [PATCH 03/16] fix: lint --- .../polykey-cli/installation.md | 40 +++++++++++-------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 5cea4ea2..65d1c288 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -1,6 +1,5 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import +Admonition from '@theme/Admonition'; # Installation @@ -46,34 +45,43 @@ libraries that Node.js requires. #### Using the Polykey CLI via the terminal -If you prefer not to use a package manager or Docker, you can install Polykey directly via the terminal using a prebuilt binary. +If you prefer not to use a package manager or Docker, you can install Polykey +directly via the terminal using a prebuilt binary. -1. Download the executable from the [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases) and rename it to `polykey`. +1. Download the executable from the + [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases) and + rename it to `polykey`. 2. Make it executable: ```sh chmod u+x ./polykey -3. Move it into a directory in your $PATH, or add the current directory to your $PATH temporarily: -* For ZSH: + ``` - echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc +3. Move it into a directory in your $PATH, or add the current directory to your + $PATH temporarily: -* For Bash: - echo 'export PATH=~/Downloads:$PATH' >> ~/.bashrc && source ~/.bashrc +- For ZSH: -4. Confirm the installation: - polykey --version +echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc + +- For Bash: echo 'export PATH=~/Downloads:$PATH' >> ~/.bashrc && source + ~/.bashrc + +4. Confirm the installation: polykey --version If it returns the version, you’re ready to use the CLI. - :::tip Important: Agent behavior +:::tip Important: Agent behavior -Once you start the Polykey agent, the terminal window will be fully occupied by the running agent process. +Once you start the Polykey agent, the terminal window will be fully occupied by +the running agent process. -To continue issuing Polykey commands (e.g., to create a vault), you must open a **new terminal window**. -If the system shuts down or the agent process stops, you’ll need to **restart the agent** before running any other commands. +To continue issuing Polykey commands (e.g., to create a vault), you must open a +**new terminal window**. +If the system shuts down or the agent process stops, you’ll need to **restart +the agent** before running any other commands. ::: From 49c41259333f317d04f8743f866a8a05c2f872a6 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 7 May 2025 02:58:43 -0600 Subject: [PATCH 04/16] docs: finalize and polish installation instructions for Polykey CLI --- .../polykey-cli/installation.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 65d1c288..412e0fde 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -59,9 +59,25 @@ directly via the terminal using a prebuilt binary. ``` -3. Move it into a directory in your $PATH, or add the current directory to your +3. Move it into a directory in your + $PATH, or add the current directory to your $PATH temporarily: +64. Confirm the installation: + polykey --version + +65. If it returns the version, you’re ready to use the CLI. + + +Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. + +To issue any further Polykey commands (for example, polykey vaults create), you must open a **new terminal window**. + +If the machine reboots or the agent exits, simply rerun polykey agent start in a terminal to restart it. + +66. --- +67. ### NixOS + - For ZSH: echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc From ef0a05e34e5f4168f3ad0bbd6cc236f70d0974d7 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 7 May 2025 03:36:49 -0600 Subject: [PATCH 05/16] docs: fix Prettier formatting issues --- docs/Getting-Started/polykey-cli/installation.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 412e0fde..6786104f 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -63,20 +63,19 @@ directly via the terminal using a prebuilt binary. $PATH, or add the current directory to your $PATH temporarily: -64. Confirm the installation: - polykey --version +4. Confirm the installation: + polykey --version -65. If it returns the version, you’re ready to use the CLI. +5. If it returns the version, you’re ready to use the CLI. Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. -To issue any further Polykey commands (for example, polykey vaults create), you must open a **new terminal window**. +To issue any further Polykey commands (for example, polykey vaults +create), you must open a **new terminal window**. -If the machine reboots or the agent exits, simply rerun polykey agent start in a terminal to restart it. - -66. --- -67. ### NixOS +If the machine reboots or the agent exits, simply rerun polykey agent +start in a terminal to restart it. 66. --- 67. ### NixOS - For ZSH: From 35a1d4c3715e9c4db1e28c1ffedde7dbd3a588ce Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 7 May 2025 04:30:43 -0600 Subject: [PATCH 06/16] docs: lint fixes --- .../polykey-cli/installation.md | 79 +++++++++++-------- 1 file changed, 48 insertions(+), 31 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 6786104f..c18336e4 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -68,38 +68,31 @@ directly via the terminal using a prebuilt binary. 5. If it returns the version, you’re ready to use the CLI. - + Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. - To issue any further Polykey commands (for example, polykey vaults create), you must open a **new terminal window**. If the machine reboots or the agent exits, simply rerun polykey agent -start in a terminal to restart it. 66. --- 67. ### NixOS +start in a terminal to restart it. + - For ZSH: -echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc +```shell +export PATH=~/Downloads:$PATH >> ~/.zshrc && source ~/.zshrc +``` -- For Bash: echo 'export PATH=~/Downloads:$PATH' >> ~/.bashrc && source - ~/.bashrc +- For Bash: + +```shell +export PATH=~/Downloads:$PATH >> ~/.bashrc && source ~/.bashrc && source +``` 4. Confirm the installation: polykey --version If it returns the version, you’re ready to use the CLI. -:::tip Important: Agent behavior - -Once you start the Polykey agent, the terminal window will be fully occupied by -the running agent process. - -To continue issuing Polykey commands (e.g., to create a vault), you must open a -**new terminal window**. -If the system shuts down or the agent process stops, you’ll need to **restart -the agent** before running any other commands. - -::: - ### NixOS We have not yet published a Nix package for Polykey. When we do, you will be @@ -127,7 +120,7 @@ $ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$( ### Other -We will be working on other distribution methods. +We are working on other distribution methods. Check back soon. @@ -165,7 +158,7 @@ this guide below to manually build and install Polykey on macOS. ::: -3. Make the Executable Runnable: Before you can run the Polykey CLI, you need to +3. Make the file Executable: Before you can run the Polykey CLI, you need to make it executable. Use the `chmod +x` command to add executable permissions to the file. Replace `polykey` with the actual name of your file if it's different: @@ -196,7 +189,7 @@ Remember to ensure that the file path matches the location of your polykey file. sudo xattr -r -d com.apple.quarantine ~/Downloads/polykey ``` -If you have completed this sucesfully, you may ignore Method #2 and move to the +If you have completed this sucessfully, you may ignore Method #2 and move to the next section on how to add polykey to your `$PATH`. ## @@ -217,8 +210,10 @@ trigger a pop-up. 1. MacOS will then prompt you with the following: -:::important Do not close this prompt. If you do, the 'Allow Anyway' option will -not appear in the next step. ::: +:::important +Do not close this prompt. If you do, the 'Allow Anyway' option will +not appear in the next step. +::: ![install1](/images/mac-install1.png) @@ -236,8 +231,10 @@ not appear in the next step. ::: sudo ./polykey ``` -:::tip When prompted in the terminal, type your administrator password and hit -enter. ::: +:::tip +When prompted in the terminal, type your administrator password and hit +enter. +::: 5. Following this, you will get another similar prompt @@ -263,6 +260,16 @@ enter. ::: To enable running the Polykey CLI from any directory in the terminal on macOS, you'll need to update your shell configuration file. + +Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. + +To issue any further Polykey commands (for example, polykey vaults +create), you must open a **new terminal window**. + +If the machine reboots or the agent exits, simply rerun polykey agent +start in a terminal to restart it. + + @@ -281,8 +288,8 @@ Make sure your path to the "polykey" executable is correct. ::: -```sh -echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc +```shell + 'export PATH=~/Downloads:$PATH >> ~/.zshrc && source ~/.zshrc ``` @@ -309,12 +316,12 @@ found and will not work. Make sure your path to the "polykey" executable is correct. Replace `downloads` with the path to the working directory -::: - -```sh -echo 'export PATH=~/downloads:$PATH' >> ~/.bashrc && source ~/.bashrc +```shell +export PATH=~/downloads:$PATH >> ~/.bashrc && source ~/.bashrc ``` +::: + @@ -417,6 +424,16 @@ polykey-cli-0.1.2-alpha.2 gygbx1qgpnhbvbcbaby3sfm19bamg7sx 0e1addd9855a 12 docker run -it 0e1addd9855a agent start --background -np /tmp/polykey ``` + +Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. + +To issue any further Polykey commands (for example, polykey vaults +create), you must open a **new terminal window**. + +If the machine reboots or the agent exits, simply rerun polykey agent +start in a terminal to restart it. + + Making sure to replace `0e1addd9855a` with your corresponding image ID. ```shell From 24fb58bb3f849a9d908270b97a96ec8a3bbf94d6 Mon Sep 17 00:00:00 2001 From: Aryan Jassal Date: Thu, 8 May 2025 10:39:52 +1000 Subject: [PATCH 07/16] chore: cleaned up installation instructions --- .../polykey-cli/installation.md | 92 ++++++++++--------- 1 file changed, 49 insertions(+), 43 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index c18336e4..ed738d11 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -1,5 +1,4 @@ -import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import -Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Installation @@ -56,26 +55,30 @@ directly via the terminal using a prebuilt binary. ```sh chmod u+x ./polykey - ``` 3. Move it into a directory in your $PATH, or add the current directory to your $PATH temporarily: -4. Confirm the installation: +4. Confirm the installation: + + ```sh polykey --version + ``` 5. If it returns the version, you’re ready to use the CLI. - -Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. -To issue any further Polykey commands (for example, polykey vaults -create), you must open a **new terminal window**. +:::important Important -If the machine reboots or the agent exits, simply rerun polykey agent -start in a terminal to restart it. - +Once you start a long‑lived command like `polykey agent start`, that process +monopolizes the current terminal window. To issue any further Polykey commands +(for example, `polykey vaults create`), you must open a **new terminal window**. + +If the machine reboots or the agent exits, simply rerun `polykey agent start` in +a terminal to restart it. + +::: - For ZSH: @@ -89,7 +92,10 @@ export PATH=~/Downloads:$PATH >> ~/.zshrc && source ~/.zshrc export PATH=~/Downloads:$PATH >> ~/.bashrc && source ~/.bashrc && source ``` -4. Confirm the installation: polykey --version +4. Confirm the installation: + ```sh + polykey --version + ``` If it returns the version, you’re ready to use the CLI. @@ -210,10 +216,8 @@ trigger a pop-up. 1. MacOS will then prompt you with the following: -:::important -Do not close this prompt. If you do, the 'Allow Anyway' option will -not appear in the next step. -::: +:::important Do not close this prompt. If you do, the 'Allow Anyway' option will +not appear in the next step. ::: ![install1](/images/mac-install1.png) @@ -231,10 +235,8 @@ not appear in the next step. sudo ./polykey ``` -:::tip -When prompted in the terminal, type your administrator password and hit -enter. -::: +:::tip When prompted in the terminal, type your administrator password and hit +enter. ::: 5. Following this, you will get another similar prompt @@ -260,31 +262,34 @@ enter. To enable running the Polykey CLI from any directory in the terminal on macOS, you'll need to update your shell configuration file. - -Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. +:::important Important -To issue any further Polykey commands (for example, polykey vaults -create), you must open a **new terminal window**. +Once you start a long‑lived command like `polykey agent start`, that process +monopolizes the current terminal window. To issue any further Polykey commands +(for example, `polykey vaults create`), you must open a **new terminal window**. -If the machine reboots or the agent exits, simply rerun polykey agent -start in a terminal to restart it. - +If the machine reboots or the agent exits, simply rerun `polykey agent start` in +a terminal to restart it. + +::: #### For ZSH (default shell on recent macOS versions): -1. Navigate (cd) into the directory where the "polykey" executable is stored. +1. Navigate (cd) into the directory where the `polykey` executable is stored. -2. Edit the Zsh configuration file to add "polykey" to your $PATH. Use the - following command, ensuring to replace ~/Downloads with the correct path to - the "polykey" executable if it's not in the downloads folder. For most users, - this path would be ~/Downloads on Debian-based systems. +2. Edit the Zsh configuration file to add `polykey` to your `$PATH`. Use the + following command, ensuring to replace `~/Downloads` with the correct path to + the `polykey` executable if it's not in the downloads folder. For most users, + this path would be `~/Downloads`. :::tip -Make sure your path to the "polykey" executable is correct. +Make sure you provide the _path_ to `polykey` instead of the actual executable. +This is not the path: `~/Downloads/polykey`. This is the correct path: +`~/Downloads`. ::: @@ -424,15 +429,16 @@ polykey-cli-0.1.2-alpha.2 gygbx1qgpnhbvbcbaby3sfm19bamg7sx 0e1addd9855a 12 docker run -it 0e1addd9855a agent start --background -np /tmp/polykey ``` - -Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. +:::important Important -To issue any further Polykey commands (for example, polykey vaults -create), you must open a **new terminal window**. +Once you start a long‑lived command like `polykey agent start`, that process +monopolizes the current terminal window. To issue any further Polykey commands +(for example, `polykey vaults create`), you must open a **new terminal window**. -If the machine reboots or the agent exits, simply rerun polykey agent -start in a terminal to restart it. - +If the machine reboots or the agent exits, simply rerun `polykey agent start` in +a terminal to restart it. + +::: Making sure to replace `0e1addd9855a` with your corresponding image ID. @@ -447,7 +453,7 @@ clientHost 127.0.0.1 clientPort 45509 agentHost :: agentPort 37468 -recoveryCode (random text recovery code goes here) +recoveryCode (random recovery code goes here) ``` @@ -487,8 +493,8 @@ Use `npm install` to setup the project. :::tip -If you have `nix-shell` available, enter into `nix-shell` and it will -automatically setup the development environment. +If you have `nix` installed and `nix-shell` available, enter into `nix-shell` +and it will automatically setup the development environment. ::: From a786b8601fbeb7d1e6aeeaf3ec767702f90e5ec2 Mon Sep 17 00:00:00 2001 From: Aryan Jassal Date: Thu, 8 May 2025 10:51:57 +1000 Subject: [PATCH 08/16] chore: updated linting command --- scripts/lint.mjs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/scripts/lint.mjs b/scripts/lint.mjs index 124fd9dd..1c57a413 100644 --- a/scripts/lint.mjs +++ b/scripts/lint.mjs @@ -49,10 +49,8 @@ async function main(argv = process.argv) { './scripts', '-type', 'f', - '-regextype', - 'posix-extended', - '-regex', - '.*\\.(sh)', + '-name', + '*.sh', '-exec', 'shellcheck', '{}', From 22eb08696d05963557a23b58b84571cfefc89cde Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 18:30:11 -0500 Subject: [PATCH 09/16] docs: clarify agent error handling when already running --- .../polykey-cli/installation.md | 84 ++++++++++++++++++- 1 file changed, 81 insertions(+), 3 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index ed738d11..17d3cb10 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -99,6 +99,32 @@ export PATH=~/Downloads:$PATH >> ~/.bashrc && source ~/.bashrc && source If it returns the version, you’re ready to use the CLI. +:::tip + +If you see an error like: + +WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may already be running + +This means the Polykey agent is already running. To manage this, you can: + +- **Check the agent status**: + +```shell +polykey agent status + +``` + +Stop the running agent: + +```shell +polykey agent stop +``` + +You must stop the current agent or use a different terminal before starting a new one. + +::: + + ### NixOS We have not yet published a Nix package for Polykey. When we do, you will be @@ -135,9 +161,9 @@ We are working on other distribution methods. Check back soon. :::info -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. +The file `polykey-cli-V.V.V-darwin-universal` is **not truly universal** — it only supports **ARM64-based Macs** (Apple Silicon: M1, M2, M3, etc). +It **will not** run on Intel-based Macs. +If you're using an Intel Mac, you must **build Polykey from source**. Instructions are provided in the [Source](#source) section. ::: @@ -273,6 +299,32 @@ a terminal to restart it. ::: +:::tip + +If you see an error like: + +WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may already be running + +This means the Polykey agent is already running. To manage this, you can: + +- **Check the agent status**: + +```shell +polykey agent status + +``` + +Stop the running agent: + +```shell +polykey agent stop +``` + +You must stop the current agent or use a different terminal before starting a new one. + +::: + + @@ -440,6 +492,32 @@ a terminal to restart it. ::: +:::tip + +If you see an error like: + +WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may already be running + +This means the Polykey agent is already running. To manage this, you can: + +- **Check the agent status**: + +```shell +polykey agent status + +``` + +Stop the running agent: + +```shell +polykey agent stop +``` + +You must stop the current agent or use a different terminal before starting a new one. + +::: + + Making sure to replace `0e1addd9855a` with your corresponding image ID. ```shell From 5d6f8811f591e6240504cada3312a6731e352738 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 21:47:06 -0500 Subject: [PATCH 10/16] docs: format fixes --- .../polykey-cli/installation.md | 34 ++++++++++--------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 17d3cb10..aaadb0cc 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -103,7 +103,8 @@ If it returns the version, you’re ready to use the CLI. If you see an error like: -WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may already be running +WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may +already be running This means the Polykey agent is already running. To manage this, you can: @@ -111,7 +112,6 @@ This means the Polykey agent is already running. To manage this, you can: ```shell polykey agent status - ``` Stop the running agent: @@ -120,11 +120,11 @@ Stop the running agent: polykey agent stop ``` -You must stop the current agent or use a different terminal before starting a new one. +You must stop the current agent or use a different terminal before starting a +new one. ::: - ### NixOS We have not yet published a Nix package for Polykey. When we do, you will be @@ -161,9 +161,11 @@ We are working on other distribution methods. Check back soon. :::info -The file `polykey-cli-V.V.V-darwin-universal` is **not truly universal** — it only supports **ARM64-based Macs** (Apple Silicon: M1, M2, M3, etc). +The file `polykey-cli-V.V.V-darwin-universal` is **not truly universal** — it +only supports **ARM64-based Macs** (Apple Silicon: M1, M2, M3, etc). It **will not** run on Intel-based Macs. -If you're using an Intel Mac, you must **build Polykey from source**. Instructions are provided in the [Source](#source) section. +If you're using an Intel Mac, you must **build Polykey from source**. +Instructions are provided in the [Source](#source) section. ::: @@ -303,7 +305,8 @@ a terminal to restart it. If you see an error like: -WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may already be running +WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may +already be running This means the Polykey agent is already running. To manage this, you can: @@ -311,7 +314,6 @@ This means the Polykey agent is already running. To manage this, you can: ```shell polykey agent status - ``` Stop the running agent: @@ -320,11 +322,11 @@ Stop the running agent: polykey agent stop ``` -You must stop the current agent or use a different terminal before starting a new one. +You must stop the current agent or use a different terminal before starting a +new one. ::: - @@ -346,7 +348,7 @@ This is not the path: `~/Downloads/polykey`. This is the correct path: ::: ```shell - 'export PATH=~/Downloads:$PATH >> ~/.zshrc && source ~/.zshrc + export PATH=~/Downloads:$PATH >> ~/.zshrc && source ~/.zshrc ``` @@ -403,7 +405,7 @@ terminal. :::warning Polykey for windows should be working but we have yet to create documentation on -the installation process for this. +the installation process for this. Check back soon. ::: @@ -496,7 +498,8 @@ a terminal to restart it. If you see an error like: -WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may already be running +WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may +already be running This means the Polykey agent is already running. To manage this, you can: @@ -504,7 +507,6 @@ This means the Polykey agent is already running. To manage this, you can: ```shell polykey agent status - ``` Stop the running agent: @@ -513,11 +515,11 @@ Stop the running agent: polykey agent stop ``` -You must stop the current agent or use a different terminal before starting a new one. +You must stop the current agent or use a different terminal before starting a +new one. ::: - Making sure to replace `0e1addd9855a` with your corresponding image ID. ```shell From 6f4e208c13cb98f8efb8d31b224f5d07833d475a Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 21:58:18 -0500 Subject: [PATCH 11/16] docs: format fixes for linting --- docs/Getting-Started/polykey-cli/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index aaadb0cc..3520d86d 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -405,7 +405,7 @@ terminal. :::warning Polykey for windows should be working but we have yet to create documentation on -the installation process for this. Check back soon. +the installation process for this. Check back soon! ::: From f5fcd171c15c13bc4e78e4289b0a785f9b841e3f Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 22:28:15 -0500 Subject: [PATCH 12/16] docs: additional information for agent outputs --- .../polykey-cli/installation.md | 35 ++++++++++++------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 3520d86d..d15e57e7 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -99,7 +99,7 @@ export PATH=~/Downloads:$PATH >> ~/.bashrc && source ~/.bashrc && source If it returns the version, you’re ready to use the CLI. -:::tip +:::tip Tip If you see an error like: @@ -114,6 +114,13 @@ This means the Polykey agent is already running. To manage this, you can: polykey agent status ``` +If the agent returns something like this: + +```shell +status DEAD +``` +Then the agent is inactive and needs to be restarted. If it returns something other than this, then it is still active. + Stop the running agent: ```shell @@ -121,7 +128,7 @@ polykey agent stop ``` You must stop the current agent or use a different terminal before starting a -new one. +new one. The currently running agent must be stopped before it can be re-run. ::: @@ -185,7 +192,7 @@ Instructions are provided in the [Source](#source) section. mv polykey-cli-V.V.V-darwin-universal polykey ``` -:::tip +:::tip Tip - Navigate into the directory where the file is saved to execute commands. - Replace `V.V.V.` with the actual version number of the file you downloaded. @@ -263,7 +270,8 @@ not appear in the next step. ::: sudo ./polykey ``` -:::tip When prompted in the terminal, type your administrator password and hit +:::tip Tip +When prompted in the terminal, type your administrator password and hit enter. ::: 5. Following this, you will get another similar prompt @@ -272,7 +280,8 @@ enter. ::: #### Click on Open and now Polykey-CLI should be running in your terminal window. -:::tip You can also verify the version of polykey that was installed with: +:::tip Tip +You can also verify the version of polykey that was installed with: ```sh ./polykey --version @@ -301,7 +310,7 @@ a terminal to restart it. ::: -:::tip +:::tip Tip If you see an error like: @@ -339,7 +348,7 @@ new one. the `polykey` executable if it's not in the downloads folder. For most users, this path would be `~/Downloads`. -:::tip +:::tip Tip Make sure you provide the _path_ to `polykey` instead of the actual executable. This is not the path: `~/Downloads/polykey`. This is the correct path: @@ -354,7 +363,7 @@ This is not the path: `~/Downloads/polykey`. This is the correct path: -:::tip +:::tip 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 @@ -370,7 +379,7 @@ found and will not work. "polykey" if the executable is not in the downloads folder. For most users, this would be `~/Downloads` -:::tip +:::tip Tip Make sure your path to the "polykey" executable is correct. Replace `downloads` with the path to the working directory @@ -384,7 +393,7 @@ export PATH=~/downloads:$PATH >> ~/.bashrc && source ~/.bashrc -:::tip +:::tip Tip You can check if the PATH environment variable for Polykey has been updated correctly by running: @@ -434,7 +443,7 @@ docker run -it "$image" ### Docker for Mac -:::tip +:::tip Tip You can install nix for MacOS and then follow the general docker instructions above. Nix for mac can be installed by running @@ -494,7 +503,7 @@ a terminal to restart it. ::: -:::tip +:::tip Tip If you see an error like: @@ -571,7 +580,7 @@ git clone https://github.com/MatrixAI/Polykey-CLI.git Use `npm install` to setup the project. -:::tip +:::tip Tip If you have `nix` installed and `nix-shell` available, enter into `nix-shell` and it will automatically setup the development environment. From 9ac2cf497d92f1f2c0b27637e00b397b72b57e25 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 22:33:39 -0500 Subject: [PATCH 13/16] docs: lint fixes --- docs/Getting-Started/polykey-cli/installation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index d15e57e7..80902cfc 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -119,7 +119,9 @@ If the agent returns something like this: ```shell status DEAD ``` -Then the agent is inactive and needs to be restarted. If it returns something other than this, then it is still active. + +Then the agent is inactive and needs to be restarted. If it returns something +other than this, then it is still active! Stop the running agent: @@ -270,9 +272,8 @@ not appear in the next step. ::: sudo ./polykey ``` -:::tip Tip -When prompted in the terminal, type your administrator password and hit -enter. ::: +:::tip Tip When prompted in the terminal, type your administrator password and +hit enter. ::: 5. Following this, you will get another similar prompt @@ -280,8 +281,7 @@ enter. ::: #### Click on Open and now Polykey-CLI should be running in your terminal window. -:::tip Tip -You can also verify the version of polykey that was installed with: +:::tip Tip You can also verify the version of polykey that was installed with: ```sh ./polykey --version From a11eb11dc8ef14822a7caa9ec85517f1b69c286c Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 23:15:10 -0500 Subject: [PATCH 14/16] docs: minor formatting fixes --- docs/Getting-Started/polykey-cli/installation.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 80902cfc..b87cccde 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -126,7 +126,7 @@ other than this, then it is still active! Stop the running agent: ```shell -polykey agent stop +polykey agent ``` You must stop the current agent or use a different terminal before starting a @@ -272,7 +272,8 @@ not appear in the next step. ::: sudo ./polykey ``` -:::tip Tip When prompted in the terminal, type your administrator password and +:::tip Tip +When prompted in the terminal, type your administrator password and hit enter. ::: 5. Following this, you will get another similar prompt @@ -281,7 +282,8 @@ hit enter. ::: #### Click on Open and now Polykey-CLI should be running in your terminal window. -:::tip Tip You can also verify the version of polykey that was installed with: +:::tip Tip +You can also verify the version of polykey that was installed with: ```sh ./polykey --version From 3e6acbf12f4a5263d334e37de70c769cf1be3a03 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 23:21:18 -0500 Subject: [PATCH 15/16] docs: minor formatting fixes for linting --- docs/Getting-Started/polykey-cli/installation.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index b87cccde..ec014d8f 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -73,7 +73,7 @@ directly via the terminal using a prebuilt binary. Once you start a long‑lived command like `polykey agent start`, that process monopolizes the current terminal window. To issue any further Polykey commands -(for example, `polykey vaults create`), you must open a **new terminal window**. +(for example, `polykey vaults create`) you must open a **new terminal window**. If the machine reboots or the agent exits, simply rerun `polykey agent start` in a terminal to restart it. @@ -126,7 +126,7 @@ other than this, then it is still active! Stop the running agent: ```shell -polykey agent +polykey agent ``` You must stop the current agent or use a different terminal before starting a @@ -272,8 +272,7 @@ not appear in the next step. ::: sudo ./polykey ``` -:::tip Tip -When prompted in the terminal, type your administrator password and +:::tip Tip When prompted in the terminal, type your administrator password and hit enter. ::: 5. Following this, you will get another similar prompt @@ -282,8 +281,7 @@ hit enter. ::: #### Click on Open and now Polykey-CLI should be running in your terminal window. -:::tip Tip -You can also verify the version of polykey that was installed with: +:::tip Tip You can also verify the version of polykey that was installed with: ```sh ./polykey --version From c7e88303dd9c8ed7dc10bdc388273f370c512d7f Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Sun, 11 May 2025 23:42:41 -0500 Subject: [PATCH 16/16] docs: lint fixes --- docs/Getting-Started/polykey-cli/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index ec014d8f..68f4a9f6 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -19,7 +19,7 @@ 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). +[here](https://discord.gg/dC32r35TeE) :::