Mxs CLI

MXS CLI

Use this skill when the task involves managing an mx-core site through mxs.

This is an operations CLI, not the old frontend SDK. Prefer it for terminal automation, admin workflows, and AI-agent-safe read/write operations.

Prerequisites

Before using the CLI:

1. Check that mxs is installed.
2. Assume Node.js 22+ is required.
3. If no profile exists yet, run mxs auth login.

Minimal checks:

command -v mxs
mxs auth status

Core model

Think in four layers:

• auth: who you are
• profile: which environment you are talking to
• content verbs: post, note, page, project, comment, snippet
• output mode: human, machine, or round-trip editing

The most important operational rule is: profile and output mode matter as much as the subcommand.

Required workflow

1. Resolve identity and target first

Before any write:

1. run mxs auth whoami or mxs auth status
2. inspect the active profile if needed: mxs profile ls
3. if the target is production, use an explicit per-invocation signal such as --profile prod

Do not rely on the inherited current profile for production writes.

2. Pick the right output mode

Use:

• --output llm for AI-agent reading
• --output readable for human terminal reading
• --json for scripts and structured automation
• --output xml for editable round trips

Examples:

mxs post list --output llm
mxs post get my-slug --output readable
mxs post get my-slug --output xml > /tmp/post.xml
mxs --json comment unread

3. Prefer read before write

For update tasks:

1. fetch the current object
2. choose either targeted flags or an editable file round trip
3. write back explicitly
4. if applicable, publish separately

Round-trip pattern:

mxs post get my-slug --output xml > /tmp/post.xml
# edit /tmp/post.xml
mxs post update my-slug --file /tmp/post.xml --open
mxs post publish my-slug

Profiles and safety

Profiles live under ~/.config/mxs/profiles/<name>/ and bundle both API URL and credentials.

Important rules:

• --profile <name> overrides everything
• MXS_PROFILE overrides the active pointer
• ~/.config/mxs/current is only the fallback
• production-marked profiles block inherited silent writes

If a write fails with profile.write_requires_explicit, retry with explicit intent:

mxs --profile prod post publish my-slug

Useful commands:

mxs profile ls
mxs profile show
mxs profile use dev
mxs profile mark prod --production

High-frequency workflows

Posts

Read:

mxs post list --output llm
mxs post get my-slug --output readable

Create:

mxs post create \
  --title "标题" \
  --slug "my-slug" \
  --content file=body.md \
  --format markdown \
  --state draft

Patch selected fields:

mxs post update my-slug --summary "摘要" --tags "cli,ai"

Publish:

mxs post publish my-slug

Notes

mxs note list --output llm
mxs note create --title "无题" --content "hello" --state draft
mxs note update my-note --content file=note.md --format markdown

Pages

mxs page list
mxs page get about --output readable
mxs page update about --file about.xml

Comments

Use this for moderation queues:

mxs comment unread
mxs comment get 141088044533944320
mxs comment reply 141088044533944320 --text "thanks for reading"
mxs comment approve 141088044533944320
mxs comment reject 141088044533944320

For destructive or bulk operations in non-TTY contexts, expect --force.

Projects

mxs project list
mxs project view my-project --output llm
mxs project create --name my-project --description "desc"

Snippets

Snippets accept either Snowflake ids or reference/name.

mxs snippet list --grouped
mxs snippet get web/theme
mxs snippet create --name theme --reference web --type json --file theme.json
mxs snippet edit web/theme

AI tasks

These commands enqueue work and usually poll until completion unless --no-wait is used.

mxs ai summary regen my-post --to en --to ja
mxs ai translate run my-post --to en
mxs ai insights refresh my-post

Content input rules

For body-like fields, --content supports:

• inline literal
• file=<path>
• - or stdin

Examples:

mxs post create --content "inline text"
mxs post create --content file=body.md
cat body.md | mxs post create --content -

For structured fields such as --meta or --images, use either:

• inline JSON
• file=<path>

LiteXML round trips

Use --output xml or --file <path> when you need stable editable documents.

Supported document envelopes:

• <mxpost>
• <mxnote>

Page editing currently reuses the post-shaped envelope.

Use XML when:

• an AI or human needs to edit title, metadata, and body together
• you want deterministic round-trip content updates
• you need a format with lower ambiguity than ad hoc flag patching

Preview

mxs preview renders LiteXML locally and does not talk to mx-core.

mxs preview ./post.xml
mxs preview ./post.xml --theme dark
mxs preview ./post.xml --save out.html
mxs preview ./post.xml --print

Use this before publishing if the task is content review rather than server mutation.

Agent usage guidance

For AI-agent tasks, prefer:

1. --output llm for reading
2. --json for machine-checked branching
3. XML envelopes for edits
4. explicit --profile on production-like writes

Recommended pattern:

mxs --profile prod post get my-slug --output llm
mxs --profile prod post get my-slug --output xml > /tmp/post.xml
mxs --profile prod post update my-slug --file /tmp/post.xml

Troubleshooting

• API URL is not configured: run mxs auth login or pass --api-url
• profile.none_active: activate or create a profile first
• profile.write_requires_explicit: add --profile <name> or MXS_PROFILE=<name>
• EDITOR is not set: export EDITOR=vim or another editor
• API key auth: use --api-key or MXS_API_KEY, not Bearer token auth

v0.3 points worth remembering

• v0.3 is an Effect-TS rewrite, but the user-facing CLI surface is intended to stay stable
• there is no first-run onboarding prompt anymore
• the public JavaScript API surface is intentionally minimal
• the CLI binary is the supported integration surface