How to Use the ai-memory CLI for HTTP Subcommands: A Complete Guide

The ai-memory CLI provides a dedicated http command family that lets you interact with ai-memory servers directly from the terminal using standard HTTP verbs.

The ai-memory CLI exposes a flexible HTTP client interface built on top of a lightweight internal client. This guide covers the command syntax, implementation details from the source code, and practical examples for scripting and automation.

HTTP Subcommand Architecture

The HTTP functionality in ai-memory follows a clean separation between transport and command logic.

Core HTTP Client (http_client.rs)

The HTTP implementation lives in crates/ai-memory-cli/src/http_client.rs. This file defines the ServerEndpoint struct, which encapsulates the base URL and provides typed convenience methods:

• get_json — Executes GET requests and deserializes JSON responses
• post_json — POST requests with JSON payloads
• put_json — Full resource replacement via PUT
• patch_json — Partial updates via PATCH
• delete_json — Resource deletion with JSON handling

All methods share common error handling and automatic Content-Type: application/json header injection for body-bearing requests.

Command Dispatch (commands/http.rs)

The CLI surface is implemented in crates/ai-memory-cli/src/commands/http.rs. This module maps CLI arguments to the appropriate ServerEndpoint method, handling:

• Path resolution relative to the server base URL
• Custom header injection via --header flags
• JSON payload construction from --data arguments
• Exit code translation from HTTP status codes

Command Syntax for ai-memory HTTP Subcommands

The unified pattern for all HTTP operations:

ai-memory http <verb> [OPTIONS] <path>

Required Arguments

• <verb> — One of: get, post, put, patch, delete, head
• <path> — Endpoint path relative to server base URL (e.g., /api/v1/pages)

Common Options

Flag	Purpose	Example
--server-url <URL>	Override configured server address	--server-url http://localhost:49374
--data <JSON>	Request body for POST/PUT/PATCH	--data '{"content":"# Hello"}'

| --header <NAME:VALUE> | Add custom headers (repeatable) | --header "Authorization: Bearer token" | | --quiet | Suppress pretty-printed output | --quiet |

Practical Examples for ai-memory HTTP Commands

The following examples assume a server running at http://127.0.0.1:49374. Adjust --server-url as needed.

GET: Retrieve Resources

Fetch a wiki page's JSON representation:

ai-memory http get /api/v1/pages/_docs/README.md \
    --server-url http://127.0.0.1:49374

POST: Create New Resources

Create a page with structured metadata:

ai-memory http post /api/v1/pages/_docs/new_page.md \
    --data '{"content":"# Hello\n\nCreated via CLI","metadata":{"author":"cli-user"}}' \

    --header "X-Request-ID: $(uuidgen)" \
    --server-url http://127.0.0.1:49374

PUT: Replace Existing Resources

Full content replacement (idempotent):

ai-memory http put /api/v1/pages/_docs/existing.md \
    --data '{"content":"# Updated Title\n\nNew body content"}' \

    --server-url http://127.0.0.1:49374

PATCH: Partial Updates

Modify only specific fields:

ai-memory http patch /api/v1/pages/_docs/existing.md \
    --data '{"metadata":{"tags":["cli","http","automation"]}}' \
    --server-url http://127.0.0.1:49374

DELETE: Remove Resources

ai-memory http delete /api/v1/pages/_docs/obsolete.md \
    --server-url http://127.0.0.1:49374

HEAD: Existence Checks

Verify a resource exists without fetching the body:

ai-memory http head /api/v1/pages/_docs/README.md \
    --server-url http://127.0.0.1:49374

Returns exit code 0 if present, non-zero if absent.

Error Handling and Exit Codes

The ai-memory HTTP CLI translates server responses into shell-appropriate behavior:

• 2xx responses: Exit code 0, JSON pretty-printed to stdout
• 4xx/5xx responses: Non-zero exit code, error payload printed to stderr for debugging

This design enables reliable scripting:

# Fail-fast script pattern

ai-memory http get /api/v1/health \
    --server-url "$AI_MEMORY_SERVER" \
    --quiet || { echo "Server unreachable"; exit 1; }

Related CLI Commands Using HTTP Internally

Several other ai-memory subcommands leverage the same http_client.rs infrastructure:

Command	Source File	HTTP Method Used
ai-memory status	crates/ai-memory-cli/src/commands/status.rs	get_json
ai-memory user show	crates/ai-memory-cli/src/commands/user.rs	get_json
ai-memory user create	crates/ai-memory-cli/src/commands/user.rs	post_json
ai-memory serve	crates/ai-memory-cli/src/commands/serve.rs	Runs server (not client)

These implementations demonstrate production patterns for the HTTP client that you can reference when building custom integrations.

Summary

• The ai-memory http subcommand family provides direct HTTP access to MCP-compatible endpoints via get, post, put, patch, delete, and head verbs.
• Core implementation resides in crates/ai-memory-cli/src/http_client.rs (ServerEndpoint struct) with command dispatch in crates/ai-memory-cli/src/commands/http.rs.
• Use --server-url to target different environments, --data for JSON payloads, and --header for authentication or custom metadata.
• Exit codes reflect HTTP status, enabling robust shell scripting and CI/CD integration.

Frequently Asked Questions

What HTTP verbs does the ai-memory CLI support?

The ai-memory http command supports get, post, put, patch, delete, and head. Each verb maps directly to the corresponding HTTP method, with automatic JSON handling for request bodies and responses.

How do I authenticate requests when using ai-memory HTTP commands?

Pass authentication tokens or API keys via the --header flag, repeatable for multiple headers: --header "Authorization: Bearer TOKEN" --header "X-Custom-Header: value". The CLI forwards these directly to the underlying HTTP request without modification.

Can I use ai-memory HTTP commands against any MCP server, or only ai-memory?

The HTTP subcommands work with any MCP-compliant HTTP endpoint. The --server-url flag accepts any base URL, and the path argument is resolved relative to that endpoint. Ensure the target server speaks the MCP protocol for meaningful responses.

Where are server settings persisted if I don't use --server-url?

The CLI reads default connection settings from its configuration system, typically populated during initial setup or via environment variables. Run ai-memory config show to inspect current defaults, or use --server-url for per-command overrides without modifying stored configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}