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

> Learn to use the ai-memory CLI for HTTP subcommands. Interact directly with ai-memory servers via the terminal using standard HTTP verbs in this complete guide.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/http_client.rs))

The HTTP implementation lives in [`crates/ai-memory-cli/src/http_client.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/commands/http.rs))

The CLI surface is implemented in [`crates/ai-memory-cli/src/commands/http.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```bash
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:

```bash
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:

```bash
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):

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash

# 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`](https://github.com/akitaonrails/ai-memory/blob/main/http_client.rs) infrastructure:

| Command | Source File | HTTP Method Used |
|---------|-------------|------------------|
| `ai-memory status` | [`crates/ai-memory-cli/src/commands/status.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/status.rs) | `get_json` |
| `ai-memory user show` | [`crates/ai-memory-cli/src/commands/user.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/user.rs) | `get_json` |
| `ai-memory user create` | [`crates/ai-memory-cli/src/commands/user.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/user.rs) | `post_json` |
| `ai-memory serve` | [`crates/ai-memory-cli/src/commands/serve.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/http_client.rs) (`ServerEndpoint` struct) with command dispatch in [`crates/ai-memory-cli/src/commands/http.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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.