CLI commands

Install and build

From the monorepo root:

pnpm --filter cli build
pnpm link --global --dir apps/cli   # optional global memost command
# or
pnpm --filter cli dev -- login

Local configuration is written to ~/.memost/config.json; authentication data is written to ~/.memost/auth.json. Both files are created with 600 permissions.

Quick start

# 1. Configure API and Dashboard URLs. The local defaults are usually enough.
memost config set api-url http://127.0.0.1:8787
memost config set web-url http://localhost:3000

# 2. Sign in with Clerk OAuth + PKCE.
memost login

# 3. Create an agent. This also saves defaultAgentId and apiKey locally.
memost agents create -n "dev-agent"

# 4. Write and search memories.
memost memories add -c "The user prefers dark mode."
memost memories search -q "theme"

Use only an API key when you do not need Clerk-managed agent administration:

memost login --api-key mst_test_xxxx
memost memories add -c "hello" -a agent_xxx

Global commands

Command	Description
memost login	Sign in with Clerk OAuth + PKCE and write auth data to ~/.memost/auth.json
memost login --token <jwt>	Paste a Clerk JWT manually
memost login --api-key <mst_*>	Save only a memory API key
memost logout	Clear local auth data
memost auth refresh	Refresh the stored OAuth access token
memost whoami	Show configuration, /health, and agent access
memost config show	Show masked local configuration
memost config set api-url <url>	Set the API worker URL
memost config set web-url <url>	Set the Dashboard URL stored in local config

agents

An Agent is the top-level memory isolation unit. Each agent contains pid scopes for processes or projects, and optional tid scopes for threads or sessions.

Command	Description
memost agents list	List agents
memost agents create -n <name>	Create an agent and return a one-time API key
memost agents get <id>	Show agent details
memost agents delete <id>	Delete an agent
memost agents use <id>	Set the default agent

Options: --description, --default-pid, --json.

keys

Requires Clerk login. These commands manage mst_* credentials.

Command	Description
memost keys list -a <agentId>	List keys
memost keys create -a <agentId>	Create a key
memost keys revoke -a <agentId> <keyId>	Revoke a key
memost keys use <raw>	Save a raw key to ~/.memost/auth.json

memories

Memory commands can use either an API key or Clerk + x-agent-id against /v1/memories.

Command	Description
memost memories add -c <text>	Write a memory
memost memories search -q <query>	Search memories
memost memories list	List memories

Options: --agent, --pid, --tid, --no-kg, --json.

Memory hierarchy

owner (Clerk user / org)
 └── agent_id          # top-level isolation unit
      └── pid          # process / project
           └── tid?    # thread / session (optional)

This matches the D1 fields used by agents, memories.pid, memories.tid, and kg_triples.

OAuth configuration

The CLI reads OAuth settings from environment variables. A typical local setup looks like this:

export MEMOST_CLI_OAUTH_CLIENT_ID=3ZsL5SoWi8Q3a2RP
export MEMOST_CLI_OAUTH_AUTHORIZE_URL=https://sharp-bird-46.clerk.accounts.dev/oauth/authorize
export MEMOST_CLI_OAUTH_TOKEN_URL=https://sharp-bird-46.clerk.accounts.dev/oauth/token
export MEMOST_CLI_OAUTH_SCOPES="email offline_access profile"
export MEMOST_CLI_OAUTH_REDIRECT_URI=http://127.0.0.1:14587/callback

Use the same mechanism for production, but point the variables at your production Clerk OAuth application and registered redirect URI.

The CLI stores access_token, refresh_token, expiration time, scope, and token type in ~/.memost/auth.json. Commands refresh the OAuth access token automatically when it is close to expiry, and memost auth refresh can refresh it manually.