Update readme

Author: lukaszcl

tools/ghsecrets/README.md

@@ -1,58 +1,169 @@
 # ghsecrets
 
-ghsecrets is a command-line tool designed to manage and set test secrets in GitHub via the GitHub CLI.
+`ghsecrets` is a command-line tool designed to manage and set test secrets in either:
+
+- **GitHub** (via the GitHub CLI), or
+- **AWS Secrets Manager**.
+
+This tool helps streamline the process of storing test secrets which can be referenced by your workflows or other services.
+
+---
 
 ## Installation
 
-To install ghsecrets CLI, you need to have Go installed on your machine. With Go installed, run the following command:
+To install the `ghsecrets` CLI, ensure you have Go installed. Then run:
 
 ```sh
 go install github.com/smartcontractkit/chainlink-testing-framework/tools/ghsecrets@latest
 ```
 
-Please install GitHub CLI to use this tool - https://cli.github.com/
+Note: If you plan to set secrets in GitHub, please also install the GitHub CLI (gh).
 
 ## Usage
 
-Set default test secrets from ~/.testsecrets file:
+### 1. Setting Secrets
+
+By default, `ghsecrets set` assumes you want to store secrets in AWS Secrets Manager, using a file from `~/.testsecrets` (if not specified). You can change the backend to GitHub, specify a custom file path, or share the AWS secret with other IAM principals. Below are common examples:
+
+#### a) Set secrets in AWS (default)
+
+This will read from `~/.testsecrets` (by default) and create/update a secret in AWS Secrets Manager:
 
 ```sh
 ghsecrets set
 ```
 
+If you’d like to specify a different file:
+
+```sh
+ghsecrets set --file /path/to/mysecrets.env
+```
+
+If you’d like to specify a custom secret name:
+
+```sh
+ghsecrets set --secret-id my-custom-secret
+```
+
+Note: For AWS backend, the tool automatically adds the `testsecrets/` prefix if it is missing. This ensures consistency and allows GitHub Actions to access all secrets with this designated prefix.
+
+If you’d like to share this secret with additional AWS IAM principals (e.g., a collaborator’s account):
+
+```sh
+ghsecrets set --shared-with arn:aws:iam::123456789012:role/SomeRole
+```
+
+You can specify multiple ARNs using commas:
+
+```sh
+ghsecrets set --shared-with arn:aws:iam::123456789012:role/SomeRole,arn:aws:iam::345678901234:root
+```
+
+#### b) Set secrets in GitHub
+
+```sh
+ghsecrets set --backend github
+```
+
+This will:
+1. Read from the default file (`~/.testsecrets`) unless `--file` is specified.
+2. Base64-encode the content.
+3. Create/update a GitHub secret using the GitHub CLI.
+
+### 2. Retrieving Secrets (AWS Only)
+
+If you want to retrieve an existing secret from AWS Secrets Manager, use:
+
+```sh
+ghsecrets get --secret-id testsecrets/MySecretName
+```
+
+By default, it prints out the Base64-encoded string. To decode it automatically:
+
+```sh
+ghsecrets get --secret-id testsecrets/MySecretName --decode
+```
+
 ## FAQ
 
-### Q: What should I do if I get "command not found: ghsecrets" after installation?
+<details>
+<summary><strong>Q: I get "command not found: ghsecrets" after installation. How do I fix this?</strong></summary>
+
+This error typically means the directory where Go installs its binaries is not in your system’s PATH. The binaries are usually installed in `$GOPATH/bin` or `$GOBIN`.
+
+Steps to fix:
+1. If you use `asdf`, run:
+
+    ```sh
+    asdf reshim golang
+    ```
+
+2. Otherwise, add your Go bin directory to PATH manually:
+    - Find your Go bin directory:
+
+    ```sh
+    echo $(go env GOPATH)/bin
+    ```
+
+    - Add it to your shell config (e.g., `~/.bashrc`, `~/.zshrc`):
+
+    ```sh
+    export PATH="$PATH:<path-to-go-bin>"
+    ```
+
+    - Reload your shell:
 
-This error typically means that the directory where Go installs its binaries is not included in your system's PATH. The binaries are usually installed in $GOPATH/bin or $GOBIN. Here's how you can resolve this issue:
+    ```sh
+    source ~/.bashrc  # or .zshrc, etc.
+    ```
 
-1. If you use `asdf` run `asdf reshim golang`
+3. Alternatively, run the tool using its full path without modifying PATH:
 
-2. Or, add Go bin directory to PATH:
+    ```sh
+    $(go env GOPATH)/bin/ghsecrets set
+    ```
 
-- First, find out where your Go bin directory is by running:
+</details>
 
-  ```sh
-  echo $(go env GOPATH)/bin
-  ```
+<details>
+<summary><strong>Q: What if my AWS SSO session expires?</strong></summary>
+
+If you see errors like `InvalidGrantException` when setting or retrieving secrets from AWS, your SSO session may have expired. Re-authenticate using:
+
+```sh
+aws sso login --profile <my-aws-profile>
+```
+
+Then try running `ghsecrets` again.
+
+</details>
+
+<details>
+<summary><strong>Q: What if I get an error that says "GitHub CLI not found"?</strong></summary>
+
+For GitHub secrets, this tool requires the GitHub CLI. Please install it first:
+
+```sh
+brew install gh
+# or
+sudo apt-get install gh
+```
+
+Then run:
+
+```sh
+gh auth login
+```
 
-  This command will print the path where Go binaries are installed, typically something like /home/username/go/bin
+and follow the prompts to authenticate.
 
-- Add the following line at the end of your shell config file (`.bashrc`, `.zshrc`), usually located at `~/`:
+</details>
 
-  ```sh
-  export PATH="$PATH:<path-to-go-bin>"
-  ```
+## Contributing
 
-- Apply the changes by sourcing the file:
-  ```sh
-  source ~/.bashrc  # Use the appropriate file like .zshrc if needed
-  ```
+Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
 
-3. Alternatively, run using the full path:
+## License
 
-   If you prefer not to alter your PATH, or if you are troubleshooting temporarily, you can run the tool directly using its full path:
+This project is licensed under the MIT License. Feel free to use, modify, and distribute it as needed.
 
-   ```sh
-   $(go env GOPATH)/bin/ghsecrets set
-   ```