Skip to content

Document token CLI JSON output and CI/Terraform bootstrapping #93

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abrookins merged 2 commits into from
Nov 19, 2025
Merged

Document token CLI JSON output and CI/Terraform bootstrapping #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ae3b0a
Document token CLI JSON output and CI/Terraform bootstrapping
abrookins Nov 18, 2025
322444f
Address review feedback on token CLI docs
abrookins Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions docs/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Copy link

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example assumes the JSON output contains a .token field (using jq -r '.token'), but the documentation doesn't specify the JSON schema returned by token add --format json.

Consider adding a brief description of the JSON output structure, for example:

**JSON Output Format:**
When using `--format json`, the command returns a JSON object with fields like:
```json
{
  "token": "the-plaintext-token",
  "hash": "abc12345...",
  "description": "CI bootstrap token",
  "expires_at": "2025-08-09T18:30:00.000000+00:00"
}


This would help users understand what fields are available for extraction in their scripts.

Copilot uses AI. Check for mistakes.
```

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
Expand Down
47 changes: 44 additions & 3 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:**

Expand All @@ -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.
Expand All @@ -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.
Copy link

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While the documentation mentions that --format json produces "a JSON array of token summaries," it doesn't show what the JSON structure looks like. Providing an example would help users who want to parse this output in scripts.

Consider adding a JSON output example:

**JSON Output Example:**
```json
[
  {
    "hash": "abc12345...xyz67890",
    "description": "API access token",
    "created_at": "2025-07-10T18:30:00.000000+00:00",
    "expires_at": "2025-08-09T18:30:00.000000+00:00"
  },
  {
    "hash": "def09876...uvw54321",
    "description": "Service account token",
    "created_at": "2025-07-10T19:00:00.000000+00:00",
    "expires_at": null
  }
]

Copilot uses AI. Check for mistakes.
**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:**
Expand All @@ -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"
}
```

Copy link

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to token list, the documentation mentions JSON output but doesn't show the structure. Providing an example would help users parse this output.

Consider adding a JSON output example:

**JSON Output Example:**
```json
{
  "hash": "abc12345...xyz67890",
  "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"
}

```suggestion

**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"
}

Copilot uses AI. Check for mistakes.
**Arguments:**
Expand Down