Document token CLI JSON output and CI/Terraform bootstrapping

Author: abrookins

docs/authentication.md

@@ -86,6 +86,57 @@ uv run agent-memory token remove abc12345
 # Remove a token without confirmation
 uv run agent-memory token remove abc12345 --force
 ```
+### CI / Terraform token bootstrapping
+
+You can use the token CLI to bootstrap authentication tokens in CI pipelines and infrastructure-as-code tools like Terraform.
+
+The key features that make this work well are:
+
+- `--format json` on token commands (`add`, `list`, `show`) for machine-readable output
+- `--token` on `token add` to register a pre-generated secret from your CI or secrets manager
+
+#### GitHub Actions example (generate token in CI)
+
+The example below generates a short-lived token during a workflow run and exposes it via `GITHUB_ENV` for later steps:
+
+```yaml
+- name: Create agent-memory token for CI
+  run: |
+    TOKEN_JSON=$(agent-memory token add \
+      --description "CI bootstrap token" \
+      --expires-days 30 \
+      --format json)
+    echo "AGENT_MEMORY_TOKEN=$(echo "$TOKEN_JSON" | jq -r '.token')" >> "$GITHUB_ENV"
+```
+
+Later steps can use `AGENT_MEMORY_TOKEN` as the bearer token when calling the API.
+
+#### Terraform example (register a pre-generated token)
+
+If you generate tokens outside Redis Agent Memory Server (for example via a secrets manager), you can register them using `--token` so the server only ever stores a hash:
+
+```hcl
+variable "agent_memory_token" {
+  type      = string
+  sensitive = true
+}
+
+resource "null_resource" "agent_memory_token" {
+  provisioner "local-exec" {
+    command = <<EOT
+      TOKEN_JSON=$(agent-memory token add \
+        --description "Terraform bootstrap" \
+        --token "${var.agent_memory_token}" \
+        --format json)
+      echo "$TOKEN_JSON" > agent-memory-token.json
+    EOT
+  }
+}
+```
+
+In both cases, store the plaintext token in a secure secret store (GitHub Actions secrets, Terraform variables, Vault, etc.). The server will hash it before storing, and the CLI will only ever print the plaintext once.
+
+
 
 **Security Features:**
 - Tokens are hashed using bcrypt before storage

docs/cli.md

@@ -134,13 +134,15 @@ Manages authentication tokens for token-based authentication. The token command
 Creates a new authentication token.
 
 ```bash
-agent-memory token add --description "DESCRIPTION" [--expires-days DAYS]
+agent-memory token add --description "DESCRIPTION" [--expires-days DAYS] [--format text|json] [--token TOKEN_VALUE]
 ```
 
 **Options:**
 
 - `--description TEXT` / `-d TEXT`: **Required**. Description for the token (e.g., "API access for service X")
 - `--expires-days INTEGER` / `-e INTEGER`: **Optional**. Number of days until token expires. If not specified, token never expires.
+- `--format [text|json]`: **Optional**. Output format. `text` (default) is human-readable; `json` is machine-readable and recommended for CI or scripting.
+- `--token TEXT`: **Optional**. Use a pre-generated token value instead of having the CLI generate one. The CLI will hash and store the token but only prints the plaintext once.
 
 **Examples:**
 
@@ -150,6 +152,12 @@ agent-memory token add --description "API access token" --expires-days 30
 
 # Create a permanent token (no expiration)
 agent-memory token add --description "Service account token"
+
+# Create a token and return JSON (for CI/scripts)
+agent-memory token add --description "CI token" --expires-days 30 --format json
+
+# Register a pre-generated token (e.g., from a secrets manager)
+agent-memory token add --description "Terraform bootstrap" --token "$MY_TOKEN" --format json
 ```
 
 **Security Note:** The generated token is displayed only once. Store it securely as it cannot be retrieved again.
@@ -159,9 +167,11 @@ agent-memory token add --description "Service account token"
 Lists all authentication tokens, showing masked token hashes, descriptions, and expiration dates.
 
 ```bash
-agent-memory token list
+agent-memory token list [--format text|json]
 ```
 
+When `--format json` is used, the command prints a JSON array of token summaries suitable for scripting and CI pipelines. The default `text` format produces human-readable output like the example below.
+
 **Example Output:**
 ```
 Authentication Tokens:
@@ -183,9 +193,11 @@ Expires: Never
 Shows detailed information about a specific token. Supports partial hash matching for convenience.
 
 ```bash
-agent-memory token show TOKEN_HASH
+agent-memory token show TOKEN_HASH [--format text|json]
 ```
 
+When `--format json` is used, the command prints a JSON object with token details (including status) suitable for scripting and CI pipelines. The default `text` format produces human-readable output.
+
 **Arguments:**
 
 - `TOKEN_HASH`: The token hash (or partial hash) to display. Can be the full hash or just the first few characters.