Document token CLI JSON output and CI/Terraform bootstrapping

[abrookins]

No description provided.

[Copilot]

Pull Request Overview

This PR adds comprehensive documentation for the CLI's JSON output format and demonstrates how to bootstrap authentication tokens in CI/CD pipelines and infrastructure-as-code workflows like Terraform.

Key changes:

• Documents the new --format json option for machine-readable output on token add, token list, and token show commands
• Documents the --token option for registering pre-generated tokens
• Adds practical examples for GitHub Actions and Terraform workflows

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.

File	Description
docs/cli.md	Added documentation for --format and --token options with usage examples
docs/authentication.md	Added new section with CI/Terraform integration examples and best practices

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

While the documentation mentions that --format json provides "machine-readable" output, it doesn't specify the JSON schema that will be returned. Users need to know what fields are available to parse the output in their scripts.

Consider adding an example of the JSON output format after line 144, such as:

**JSON Output Example:**
```json
{
  "token": "the-generated-or-provided-token",
  "hash": "abc12345...",
  "description": "CI token",
  "expires_at": "2025-08-09T18:30:00.000000+00:00"
}

This would make the JSON examples more actionable.
```suggestion

**JSON Output Example:**
```json
{
  "token": "the-generated-or-provided-token",
  "hash": "abc12345...",
  "description": "CI token",
  "expires_at": "2025-08-09T18:30:00.000000+00:00"
}

• --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.

[Copilot]

Minor style inconsistency: The spacing around "/" in "CI / Terraform" is unconventional. The standard style is to write it without spaces as "CI/Terraform".

Suggested change

	### CI / Terraform token bootstrapping
	### CI/Terraform token bootstrapping

[Copilot]

The token value "${var.agent_memory_token}" is passed directly to the shell command without proper escaping. If the token contains special shell characters (like $, backticks, quotes, etc.), this could cause command injection or parsing errors.

Consider adding a note about escaping or using a safer approach, such as:

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

Or better yet, pass it as an environment variable:

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

Suggested change

	command = <<EOT
	TOKEN_JSON=$(agent-memory token add \
	--description "Terraform bootstrap" \
	--token "${var.agent_memory_token}" \
	environment = {
	AGENT_MEMORY_TOKEN = var.agent_memory_token
	}
	command = <<EOT
	TOKEN_JSON=$(agent-memory token add \
	--description "Terraform bootstrap" \
	--token "$AGENT_MEMORY_TOKEN" \

[Copilot]

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]

The statement "the CLI will only ever print the plaintext once" is inaccurate when using --token to provide a pre-generated token. In that scenario, the CLI doesn't print the token at all since it was provided by the user. This statement only applies to the default behavior where the CLI generates a new token.

Consider revising to: "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."

Suggested change

	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.
	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.

[Copilot]

[nitpick] The null_resource with local-exec provisioner has been deprecated in favor of terraform_data in Terraform 1.4+. While null_resource still works, consider updating the example to use the modern approach:

resource "terraform_data" "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
  }
}

Alternatively, mention that users on Terraform <1.4 should use null_resource while newer versions should use terraform_data.

[Copilot]

[nitpick] There are two consecutive blank lines here. Standard markdown formatting typically uses a single blank line between sections.

Suggested change

[Copilot]

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]

The phrase "only prints the plaintext once" is misleading for the --token option. When a pre-generated token is provided via --token, the CLI doesn't print or display the token - it only confirms registration. This wording is more accurate for the default behavior (without --token) where the CLI generates and displays a new token.

Consider revising to: "Use a pre-generated token value instead of having the CLI generate one. The CLI will hash and store the provided token. Note: When using this option, ensure you have securely stored the plaintext token as the CLI will not display it."

Suggested change

	- `--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.
	- `--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. Note: When using this option, ensure you have securely stored the plaintext token as the CLI will not display it.

[Copilot]

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.