mxs CLI AI Author

Use mxs as the deterministic interface for mx-core content operations without opening the admin UI. Load only the references needed for the requested operation.

Reference Map

Mandatory Workflow

┌──────────────────────┐
│ Identify operation   │
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ Load relevant refs   │
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ Confirm target/auth  │
└──────────┬───────────┘
           ▼
     ◆ Mutation? ◆
      /          \
     ▼            ▼
┌──────────┐  ┌──────────────────────┐
│ Read cmd │  │ Dry run if supported │
└────┬─────┘  └──────────┬───────────┘
     │                   ▼
     │          ┌──────────────────────┐
     │          │ Execute mutation     │
     │          └──────────┬───────────┘
     │                   ▼
     └─────────>┌──────────────────────┐
                │ Verify read-back     │
                └──────────────────────┘

Required Safety Rules

• Always use machine-readable output: pass --json for mutations and reads unless the task explicitly asks for human output.
• Never print access tokens, refresh tokens, cookies, API keys, or raw credential files.
• Treat MXSAPIURL, MXSTOKEN, MXSAPI_KEY, --api-url, --token, and --api-key as execution context, not content.
• Do not publish to production unless the user explicitly requested publication or the configured target has been confirmed as the intended target.
• If testing the write path without publication, set <state>draft</state> or pass --state draft.
• After any create, edit, update, publish, or unpublish operation, read the resource back and verify observable fields.
• For destructive operations, prefer --dry-run first where supported, then require an explicit user request or confirmed intended target before using delete --force.

Target Confirmation

Before writing, establish the target. See [Auth, Config, And Output](references/auth-config-output.md) for complete auth and configuration behavior.

mxs auth status --json
mxs auth whoami --json
mxs category list --json

If the command returns fetch failed, start or select the intended mx-core server before continuing. In this repository, local development normally uses http://localhost:2333, with no /api/v2 prefix. If writes return auth.expired while reads work, confirm whether the available credential is an API key. API keys must be passed through MXSAPIKEY or --api-key, not MXS_TOKEN.

Command Coverage

The CLI command surface includes auth, post, note, page, category, topic, comment, snippet, and config. Before using an unfamiliar command or flag, read [Command Index](references/command-index.md). Do not infer unsupported flags from another resource type.

Verification Checklist

Output Discipline

• Mutations: use --json.
• Script reads: use --json.
• Agent read-back for document content: use --output llm or --output envelope.
• Human inspection: use --output readable only when requested.
• Troubleshooting: use --verbose without printing credentials.