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

CODEBLOCK0

Then run it as a normal installed binary:

CODEBLOCK1

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:

CODEBLOCK2

The CLI reads configuration with this precedence:

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

Expected variables:

CODEBLOCK3

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 INLINECODE11
• Do not print secret values back to the user
• Do not suggest editing committed files for secrets; prefer shell env vars or local INLINECODE12

Output Format

Default: human-readable text

CODEBLOCK4

Structured output: --json

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

CODEBLOCK5

Command Reference

Configuration

CODEBLOCK6

Read Operations

CODEBLOCK7

Write Operations

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

CODEBLOCK8

Agent Workflows

List memos safely

CODEBLOCK9

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

CODEBLOCK10

Fetch one memo before updating it

CODEBLOCK11

Search then inspect the matching memo

CODEBLOCK12

Filter with CEL expression

CODEBLOCK13

Paginate through memo lists

CODEBLOCK14

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

CODEBLOCK15

The CLI appends DEFAULT_TAG automatically when configured.

Delete a memo safely

CODEBLOCK16

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

CODEBLOCK17

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 INLINECODE23
• Do not invent memos:// or other URI forms for CLI commands
• INLINECODE25 and tag remove work with memo IDs and rely on the client behavior already implemented in the repo

Error Reference

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 INLINECODE44
• 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: INLINECODE50
• Preflight: INLINECODE51
• List memos: INLINECODE52
• List as JSON: INLINECODE53
• Get one memo: INLINECODE54
• Search text: INLINECODE55
• CEL filter: INLINECODE56
• Create memo: INLINECODE57
• Update memo: INLINECODE58
• Delete memo: INLINECODE59
• Add comment: INLINECODE60
• Remove tag: INLINECODE61
• List users: INLINECODE62