From 5315d426d2165aebb54cad74d52a2effcd7975fb Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Mon, 12 May 2025 13:44:41 -0500 Subject: [PATCH 1/7] docs: clarify Linux PATH setup for manual Polykey installation --- .../polykey-cli/installation.md | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 68f4a9f..ff85786 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -57,9 +57,16 @@ directly via the terminal using a prebuilt binary. chmod u+x ./polykey ``` -3. Move it into a directory in your - $PATH, or add the current directory to your - $PATH temporarily: +3. Add the executable to your PATH + +To run `polykey` from anywhere, you need to add the directory containing it to your `PATH`. You can either: + +- Move `polykey` into an existing directory already in your `PATH` (e.g., `/usr/local/bin`), **or** +- Add the current directory to your `PATH`, either temporarily or permanently: + +**Temporary (until terminal closes):** +```sh +export PATH="$PWD:$PATH" 4. Confirm the installation: @@ -83,16 +90,18 @@ a terminal to restart it. - For ZSH: ```shell -export PATH=~/Downloads:$PATH >> ~/.zshrc && source ~/.zshrc +export PATH="$HOME/Downloads:$PATH"' >> ~/.zshrc && source ~/.zshrc ``` - For Bash: +– For Bash: + ```shell -export PATH=~/Downloads:$PATH >> ~/.bashrc && source ~/.bashrc && source +echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.bashrc && source ~/.bashrc ``` -4. Confirm the installation: +4. Confirm the installation with: ```sh polykey --version ``` From 366bfcf47e937a6a9e82ede48edd77cbadfd6dc6 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Mon, 12 May 2025 14:34:42 -0500 Subject: [PATCH 2/7] chore: apply lint fixes to installation docs --- docs/Getting-Started/polykey-cli/installation.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index ff85786..26b5605 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -59,20 +59,23 @@ directly via the terminal using a prebuilt binary. 3. Add the executable to your PATH -To run `polykey` from anywhere, you need to add the directory containing it to your `PATH`. You can either: +To run `polykey` from anywhere, you need to add the directory containing it to +your `PATH`. You can either: -- Move `polykey` into an existing directory already in your `PATH` (e.g., `/usr/local/bin`), **or** +- Move `polykey` into an existing directory already in your `PATH` (e.g., + `/usr/local/bin`), **or** - Add the current directory to your `PATH`, either temporarily or permanently: **Temporary (until terminal closes):** -```sh + +````sh export PATH="$PWD:$PATH" 4. Confirm the installation: ```sh polykey --version - ``` +```` 5. If it returns the version, you’re ready to use the CLI. @@ -130,7 +133,7 @@ status DEAD ``` Then the agent is inactive and needs to be restarted. If it returns something -other than this, then it is still active! +other than this, then it is still active. Stop the running agent: From a2ae37f5e714d59e890aadab763efecb297ab7a7 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 14 May 2025 01:21:28 -0500 Subject: [PATCH 3/7] docs: finalize CLI PATH instructions and confirm linted --- docs/Getting-Started/polykey-cli/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 26b5605..3e8c4bd 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -68,14 +68,14 @@ your `PATH`. You can either: **Temporary (until terminal closes):** -````sh +```sh export PATH="$PWD:$PATH" 4. Confirm the installation: ```sh polykey --version -```` +``` 5. If it returns the version, you’re ready to use the CLI. From 0f8d46fb12e0fd8f181558536aa76e250550b689 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 14 May 2025 01:22:52 -0500 Subject: [PATCH 4/7] docs: fix final unstaged changes in installation.md --- docs/Getting-Started/polykey-cli/installation.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 3e8c4bd..361ae64 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -93,13 +93,11 @@ a terminal to restart it. - For ZSH: ```shell -export PATH="$HOME/Downloads:$PATH"' >> ~/.zshrc && source ~/.zshrc +echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.zshrc && source ~/.zshrc ``` - For Bash: -– For Bash: - ```shell echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.bashrc && source ~/.bashrc ``` @@ -120,8 +118,8 @@ already be running This means the Polykey agent is already running. To manage this, you can: -- **Check the agent status**: - +**Check the agent status**: +pm ```shell polykey agent status ``` From 5ed7bd5b6273c90d8fb2b10054e39d56ee27ede3 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 14 May 2025 01:39:54 -0500 Subject: [PATCH 5/7] docs: format installation.md with Prettier --- docs/Getting-Started/polykey-cli/installation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 361ae64..e87a6c9 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -68,14 +68,14 @@ your `PATH`. You can either: **Temporary (until terminal closes):** -```sh +````sh export PATH="$PWD:$PATH" 4. Confirm the installation: ```sh polykey --version -``` +```` 5. If it returns the version, you’re ready to use the CLI. @@ -119,7 +119,7 @@ already be running This means the Polykey agent is already running. To manage this, you can: **Check the agent status**: -pm + ```shell polykey agent status ``` From e482f40e82d0f2473fdfac0e7dedd2dd94db1e84 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 14 May 2025 02:17:50 -0500 Subject: [PATCH 6/7] docs: finalize reviewed CLI installation changes post-lint --- .../polykey-cli/installation.md | 56 ++++++++++++++++--- 1 file changed, 47 insertions(+), 9 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index e87a6c9..5ed59cc 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -68,14 +68,15 @@ your `PATH`. You can either: **Temporary (until terminal closes):** -````sh +```shell export PATH="$PWD:$PATH" +``` 4. Confirm the installation: - ```sh +```shell polykey --version -```` +``` 5. If it returns the version, you’re ready to use the CLI. @@ -102,10 +103,42 @@ echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.zshrc && source ~/.zshrc echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.bashrc && source ~/.bashrc ``` +:::tip Setting PATH across operating systems + +Where you place the `polykey` binary — and how you add it to your `PATH` — +depends on your OS: + +- **Linux**: Preferred location is `~/.local/bin` (you may need to create it + using `mkdir -p ~/.local/bin`). Make sure this directory is included in your + `$PATH` — often via `~/.bashrc`, `~/.bash_profile`, or `~/.profile`. + +- **macOS**: Same as Linux — use `~/.local/bin` or `~/bin`. Update your `$PATH` + in `~/.zshrc` (ZSH is default on macOS since Catalina) or `~/.bash_profile` if + using Bash. + +- **Windows**: Place `polykey.exe` into: + +```shell +%USERPROFILE%\AppData\Local\Microsoft\WindowsApps +``` + +This location is typically already included in the system PATH. + +To verify it’s working, run: + +```shell +which polykey +polykey --version + +``` + +::: + 4. Confirm the installation with: - ```sh + +```shell polykey --version - ``` +``` If it returns the version, you’re ready to use the CLI. @@ -282,8 +315,11 @@ 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 @@ -291,7 +327,9 @@ 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 @@ -421,7 +459,7 @@ terminal. -:::warning +:::warning Warning Polykey for windows should be working but we have yet to create documentation on the installation process for this. Check back soon! From bb5a78c4f0e0ffdc441fab25643d1d6a8769ea60 Mon Sep 17 00:00:00 2001 From: Aryan Jassal Date: Thu, 15 May 2025 14:17:05 +1000 Subject: [PATCH 7/7] chore: cleaned up linux instructions --- .../polykey-cli/installation.md | 89 +++++++++++-------- 1 file changed, 51 insertions(+), 38 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/installation.md b/docs/Getting-Started/polykey-cli/installation.md index 5ed59cc..308f65e 100644 --- a/docs/Getting-Started/polykey-cli/installation.md +++ b/docs/Getting-Started/polykey-cli/installation.md @@ -53,9 +53,9 @@ directly via the terminal using a prebuilt binary. 2. Make it executable: - ```sh - chmod u+x ./polykey - ``` +```sh +chmod u+x ./polykey +``` 3. Add the executable to your PATH @@ -64,45 +64,37 @@ your `PATH`. You can either: - Move `polykey` into an existing directory already in your `PATH` (e.g., `/usr/local/bin`), **or** -- Add the current directory to your `PATH`, either temporarily or permanently: - -**Temporary (until terminal closes):** - -```shell -export PATH="$PWD:$PATH" -``` +- Add the polykey directory to your `PATH`, either temporarily or permanently: -4. Confirm the installation: +**Temporarily (until terminal closes):** ```shell - polykey --version +export PATH="$HOME/Downloads:$PATH" ``` -5. If it returns the version, you’re ready to use the CLI. - -:::important Important - -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. +**Permanently:** -::: - -- For ZSH: + + +To permanently add `polykey` to `PATH` on zsh, run the following command. ```shell echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.zshrc && source ~/.zshrc ``` -- For Bash: + + +To permanently add `polykey` to `PATH` on bash, run the following command. ```shell echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.bashrc && source ~/.bashrc ``` + + + +--- + :::tip Setting PATH across operating systems Where you place the `polykey` binary — and how you add it to your `PATH` — @@ -129,7 +121,6 @@ To verify it’s working, run: ```shell which polykey polykey --version - ``` ::: @@ -137,17 +128,29 @@ polykey --version 4. Confirm the installation with: ```shell - polykey --version +polykey --version ``` If it returns the version, you’re ready to use the CLI. +:::important Important + +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. + +::: + :::tip Tip 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: @@ -169,7 +172,7 @@ other than this, then it is still active. Stop the running agent: ```shell -polykey agent +polykey agent stop ``` You must stop the current agent or use a different terminal before starting a @@ -187,19 +190,19 @@ 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 @@ -362,17 +365,27 @@ 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: -- **Check the agent status**: +**Check the agent status**: ```shell 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 @@ -380,7 +393,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. :::