Mmk Shared

MMK CLI — Shared Foundation

Background knowledge for all skills that use the mmk CLI.

Prerequisites

The mmk CLI must be installed and configured:

# Install
npm install -g @magic-meal-kits/cli@beta

# Configure server endpoint
mmk config set server <server-url>

# Authenticate
mmk auth login

Global Flags

Critical for skill composition: Always use -o json when composing multiple commands or parsing output programmatically. Table output is for human display only.

Error Format

When a command fails, the CLI outputs to stderr:

✗ HTTP <status_code>
  <error message>

With -o json, errors are returned as:

{"error": "<error message>"}

The error message comes from the server's JSON response {"error": "..."} field. The CLI exits with a non-zero status code on failure.

Common Error Patterns

Auth Troubleshooting

If commands return authentication errors:

1. Run mmk auth status to check current auth state
2. Run mmk auth login to re-authenticate
3. Verify server URL: mmk config get server

Shell Quoting (Important)

Any positional argument containing ?, &, *, #, (, ), spaces, or other shell-special characters must be wrapped in quotes — most commonly a YouTube or Notion URL like https://www.youtube.com/watch?v=....

# WRONG — zsh (macOS default shell) treats `?` as a glob wildcard and fails
# with "zsh: no matches found: ..." before mmk even runs
mmk youtube transcript https://www.youtube.com/watch?v=s9rAFOoAv-U

# CORRECT — always quote URLs
mmk youtube transcript "https://www.youtube.com/watch?v=s9rAFOoAv-U"

This is a shell behavior, not an mmk bug — bash mostly tolerates unquoted ?, but zsh (macOS default since Catalina, including over SSH) does not. Always quote URL arguments regardless of which shell you're on.

Command Reference

Top-level commands available via mmk:

• mmk notion — Notion page, workspace, team, people, database, meeting, comment, user, emoji, view management (46 commands)
• mmk paymint — Payment/invoice management (7 commands)
• mmk threads — Threads account data: posts, insights, replies (3 commands)
• mmk youtube — YouTube tools: transcript, metadata, video type (3 commands)
• mmk plaud — Plaud voice recorder: file list/transcript/summary/tabs, search, admin passthroughs; write ops rename/organize/trash (trash soft-deletes notes) (28 commands)
• mmk auth — Authentication
• mmk config — CLI configuration
• mmk doctor — Check CLI setup and server connectivity
• mmk plan — Show current plan and feature access
• mmk status — Show server health and connection status
• mmk upgrade — Check for and install CLI updates (--check for check-only mode)