Merge pull request #93 from redis/feature/token-cli-bootstrap-docs

Document token CLI JSON output and CI/Terraform bootstrapping

Author: abrookins

docs/authentication.md

@@ -86,6 +86,76 @@ 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.
+**JSON output format for `token add`**
+
+When you use `--format json`, `agent-memory token add` returns a JSON object with fields like:
+
+```json
+{
+  "token": "the-plaintext-token",
+  "hash": "abc12345def67890...",
+  "description": "CI bootstrap token",
+  "created_at": "2025-07-10T18:30:00.000000+00:00",
+  "expires_at": "2025-08-09T18:30:00.000000+00:00"
+}
+```
+
+You can extract any of these fields in your scripts (for example, `.token` or `.hash` with `jq`).
+
+#### 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 "terraform_data" "agent_memory_token" {
+  provisioner "local-exec" {
+    environment = {
+      AGENT_MEMORY_TOKEN = var.agent_memory_token
+    }
+
+    command = <<EOT
+      TOKEN_JSON=$(agent-memory token add \
+        --description "Terraform bootstrap" \
+        --token "$AGENT_MEMORY_TOKEN" \
+        --format json)
+      echo "$TOKEN_JSON" > agent-memory-token.json
+    EOT
+  }
+}
+```
+
+For Terraform versions earlier than 1.4, you can use a `null_resource` instead of `terraform_data`.
+
+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. When the CLI generates a token (without `--token`), it displays the plaintext only once; when using `--token` with a pre-generated value, ensure you've already stored it securely.
 
 **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 provided token; make sure you've stored the plaintext securely in your secrets manager or CI system.
 
 **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,7 +167,28 @@ 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.
+**JSON Output Example:**
+```json
+[
+  {
+    "hash": "abc12345def67890xyz",
+    "description": "API access token",
+    "created_at": "2025-07-10T18:30:00.000000+00:00",
+    "expires_at": "2025-08-09T18:30:00.000000+00:00",
+    "status": "Active"
+  },
+  {
+    "hash": "def09876uvw54321...",
+    "description": "Service account token",
+    "created_at": "2025-07-10T19:00:00.000000+00:00",
+    "expires_at": null,
+    "status": "Never Expires"
+  }
+]
 ```
 
 **Example Output:**
@@ -183,7 +212,19 @@ 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.
+**JSON Output Example:**
+```json
+{
+  "hash": "abc12345def67890xyz",
+  "description": "API access token",
+  "created_at": "2025-07-10T18:30:00.000000+00:00",
+  "expires_at": "2025-08-09T18:30:00.000000+00:00",
+  "status": "Active"
+}
 ```
 
 **Arguments:**