memos-cli

name	memos-cli
description	Use when a user needs to read, search, create, update, delete, comment on, tag, or inspect Memos data through this repository's Go CLI, especially for requests mentioning Memos, memo, memos, 备忘录, 备忘, 笔记, 便签, 随记, 记录, 标签, 评论, comments, tags, or note-taking workflows instead of handwritten HTTP API calls.

memos-cli — Repository Memos CLI Skill

Install: go install github.com/rogeecn/memos-cli@latest
Binary form: memos-cli
Primary purpose: Use this repository's Go CLI to perform Memos operations from the terminal.

Overview

This repository contains a Go CLI named memos for common Memos operations.

Agents should prefer this CLI when the user asks to list memos, fetch memo details, search content, apply CEL filters, create or update memos, delete memos, add comments, remove tags, or inspect users. This also applies when the user uses Chinese terms such as 备忘录, 备忘, 笔记, 便签, 随记, 记录, 标签, or 评论 instead of memo or Memos. The CLI already handles configuration loading, JSON output, memo formatting, and memo ID normalization behavior implemented in the repo.

When to Use

Use this skill when:

• The user wants to inspect or modify Memos data from this repository
• The request mentions Memos, memo, memos, 备忘录, 备忘, 笔记, 便签, 随记, 记录, 标签, 评论, comment, or tag
• The task should use the repo's real command surface instead of handwritten HTTP requests
• The user needs terminal output or structured JSON from Memos commands
• The agent needs a safe preflight check for local config before calling Memos APIs

Do not use this skill when:

• The user is asking to develop the CLI itself rather than use it
• The task is purely about source code changes with no need to run Memos commands

Setup

Install the CLI first:

go install github.com/rogeecn/memos-cli@latest

Then run it as a normal installed binary:

memos-cli --help

Use memos-cli as the canonical entrypoint. Do not use go run . in this skill.

Configuration

IMPORTANT FOR AGENTS: Before executing any command that talks to the Memos API, first run:

memos-cli config check

The CLI reads configuration with this precedence:

1. Shell environment variable
2. Current directory .env
3. Missing

Expected variables:

MEMOS_URL=http://localhost:5230
MEMOS_API_KEY=your-api-key
MEMOS_ADMIN_API_KEY=your-admin-api-key
DEFAULT_TAG=cli

Preflight Rules

• If MEMOS_URL is missing, stop and ask the user for the Memos base URL
• If MEMOS_API_KEY is missing, stop and ask the user to provide or export it
• If the task needs user list, also require MEMOS_ADMIN_API_KEY
• Do not print secret values back to the user
• Do not suggest editing committed files for secrets; prefer shell env vars or local .env

Output Format

Default: human-readable text

memos-cli memo list
memos-cli memo get <memo-id>

Structured output: --json

Use --json whenever the task needs machine-readable data, IDs for follow-up steps, or filtering with shell tools.

memos-cli --json memo list

Command Reference

Configuration

memos-cli config check

Read Operations

memos-cli memo list
memos-cli memo list --page-size 20
memos-cli memo list --page-token <token>
memos-cli memo get <memo-id>
memos-cli search "keyword"
memos-cli filter --expr "visibility == 'PRIVATE'"
memos-cli user list

Write Operations

The content field supports Markdown. Agents can pass plain text or Markdown content to memo and comment commands.

memos-cli memo create "# Weekly Note\n\n- shipped feature\n- fixed bug"
memos-cli memo create "memo content" --tag release --tag cli
memos-cli memo create "memo content" --visibility PUBLIC
memos-cli memo update <memo-id> --content "## Updated\n\nThis memo now uses **Markdown**."
memos-cli memo update <memo-id> --visibility PUBLIC
memos-cli memo delete <memo-id> --yes
memos-cli comment create <memo-id> "Looks good.\n\n- reviewed\n- approved"
memos-cli tag remove <memo-id> <tag>

Agent Workflows

List memos safely

memos-cli config check
memos-cli memo list

Note: memo list lists memos using the API default ordering. Treat it as the current list view, not a guaranteed dedicated recent command.

List memos as JSON for follow-up actions

memos-cli config check
memos-cli --json memo list

Fetch one memo before updating it

memos-cli memo get <memo-id>
memos-cli memo update <memo-id> --content "new content"

Search then inspect the matching memo

memos-cli --json search "deploy"
memos-cli memo get <memo-id>

Filter with CEL expression

memos-cli filter --expr "createTime > timestamp('2026-01-01T00:00:00Z') && visibility == 'PRIVATE'"

Paginate through memo lists

memos-cli memo list --page-size 20
memos-cli memo list --page-size 20 --page-token <next-token>

In text mode, the CLI prints Next page token: ... when another page exists. In JSON mode, inspect nextPageToken.

Create a memo with default and explicit tags

memos-cli memo create "ship checklist ready" --tag release --tag weekly

The CLI appends DEFAULT_TAG automatically when configured.

Delete a memo safely

memos-cli memo delete <memo-id> --yes

Deletion requires explicit --yes. If the user asks to delete a memo and has not clearly confirmed, ask before running it.

List users via admin API

go run . config check
go run . user list

If MEMOS_ADMIN_API_KEY is missing, stop and ask the user to provide admin credentials.

ID Rules

• Prefer passing the memo's plain ID, such as abc123
• Do not invent memos:// or other URI forms for CLI commands
• comment create and tag remove work with memo IDs and rely on the client behavior already implemented in the repo

Error Reference

Error or symptom	Likely cause	Agent action
MEMOS_URL is required	Base URL missing	Ask user for MEMOS_URL or local .env
MEMOS_API_KEY is required	API key missing	Ask user for MEMOS_API_KEY
MEMOS_ADMIN_API_KEY is required	Admin command without admin key	Ask user for admin key before user list
update requires --content or --visibility	Update called with no changes	Re-run with at least one change flag
delete requires --yes	Delete missing confirmation flag	Re-run only after explicit confirmation
empty or unexpected search results	Filter/query too narrow or API data differs	Try --json and inspect returned structure
next page not visible	Pagination token not supplied	Re-run with --page-token

Safety Notes

• Treat API keys as secrets; never echo them back in full
• Prefer config check over guessing whether configuration exists
• Prefer --json for agent follow-up logic and ID extraction
• Avoid destructive commands unless the user explicitly requested them
• Do not commit .env or other local secret material

Common Mistakes

• Using go run . or go run ./cmd/memos instead of the installed memos-cli binary
• Running API commands before config check
• Forgetting --json when later steps need a memo ID or token
• Assuming memo list is a dedicated recent endpoint rather than the default list API
• Forgetting --yes for deletions
• Calling user list without admin credentials

Quick Reference

• Install: go install github.com/rogeecn/memos-cli@latest
• Preflight: memos-cli config check
• List memos: memos-cli memo list
• List as JSON: memos-cli --json memo list
• Get one memo: memos-cli memo get <memo-id>
• Search text: memos-cli search "keyword"
• CEL filter: memos-cli filter --expr "..."
• Create memo: memos-cli memo create "content"
• Update memo: memos-cli memo update <memo-id> --content "..."
• Delete memo: memos-cli memo delete <memo-id> --yes
• Add comment: memos-cli comment create <memo-id> "..."
• Remove tag: memos-cli tag remove <memo-id> <tag>
• List users: memos-cli user list