@mx-space/cli 0.6.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -0
- package/ROADMAP.md +5 -0
- package/dist/bin/mxs.mjs +1 -1
- package/dist/index.d.mts +19 -1
- package/dist/index.mjs +1 -1
- package/dist/{mxs-DmOnpQrK.mjs → mxs-BxXhmqqF.mjs} +3656 -3032
- package/package.json +4 -2
- package/skills/auth-config.md +70 -0
- package/skills/authoring.md +175 -0
- package/skills/commands-auth.md +19 -0
- package/skills/commands-category.md +20 -0
- package/skills/commands-comment.md +47 -0
- package/skills/commands-config.md +30 -0
- package/skills/commands-note.md +53 -0
- package/skills/commands-page.md +32 -0
- package/skills/commands-post.md +51 -0
- package/skills/commands-preview.md +58 -0
- package/skills/commands-profile.md +22 -0
- package/skills/commands-topic.md +18 -0
- package/skills/output-modes.md +45 -0
- package/skills/overview.md +42 -0
- package/skills/safety.md +114 -0
- package/skills/workflow.md +49 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mx-space/cli",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.2",
|
|
4
4
|
"description": "Command line interface for mx-space (mx-core) — auth, content, configuration",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mx-space",
|
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
"files": [
|
|
28
28
|
"bin",
|
|
29
29
|
"dist",
|
|
30
|
+
"skills",
|
|
30
31
|
"README.md",
|
|
31
32
|
"ROADMAP.md"
|
|
32
33
|
],
|
|
@@ -52,7 +53,8 @@
|
|
|
52
53
|
"@effect/platform": "0.96.1",
|
|
53
54
|
"@effect/platform-node": "0.106.0",
|
|
54
55
|
"@haklex/rich-headless": "0.13.0",
|
|
55
|
-
"@haklex/rich-litexml": "0.
|
|
56
|
+
"@haklex/rich-litexml": "0.15.2",
|
|
57
|
+
"@haklex/rich-litexml-cli": "0.15.2",
|
|
56
58
|
"@lexical/headless": "^0.44.0",
|
|
57
59
|
"better-auth": "^1.6.9",
|
|
58
60
|
"effect": "3.21.2",
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: auth-config
|
|
3
|
+
title: Profiles, env vars, target selection
|
|
4
|
+
description: how to confirm and override the deployment the CLI is talking to
|
|
5
|
+
order: 50
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Auth, config, and target selection
|
|
9
|
+
|
|
10
|
+
Use this reference before target-sensitive operations.
|
|
11
|
+
|
|
12
|
+
## Target confirmation
|
|
13
|
+
|
|
14
|
+
| Step | Command | Purpose |
|
|
15
|
+
| ----------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
16
|
+
| Auth state | `mxs auth status --json` | Confirm token presence, expiry, refresh-token availability, stored user. |
|
|
17
|
+
| Identity | `mxs auth whoami --json` | Confirm authenticated user and resolved API URL. |
|
|
18
|
+
| Content context | `mxs category list --json` | Confirm category/tag availability for posts. |
|
|
19
|
+
| Note context | `mxs topic list --json` | Confirm topic availability for notes. |
|
|
20
|
+
|
|
21
|
+
Local development normally uses `http://localhost:2333` as the origin. Do not add `/api/v3` to `MXS_API_URL` or `--api-url`; the CLI derives API and auth bases.
|
|
22
|
+
|
|
23
|
+
## Authentication inputs
|
|
24
|
+
|
|
25
|
+
| Input | Meaning | Use case |
|
|
26
|
+
| ---------------------------- | ------------------------------------------------------ | ----------------------------------------- |
|
|
27
|
+
| `mxs auth login` | Device authorization flow. | Interactive credential setup. |
|
|
28
|
+
| `MXS_TOKEN` or `--token` | Better Auth access token as bearer auth. | Session/OIDC token override. |
|
|
29
|
+
| `MXS_API_KEY` or `--api-key` | API key sent as `x-api-key`. | Server API key workflows. |
|
|
30
|
+
| stored credentials | `~/.config/mxs/credentials.json` by default. | Normal CLI state after login. |
|
|
31
|
+
|
|
32
|
+
If reads work but writes return `auth.expired`, verify whether the credential is an API key incorrectly supplied as a bearer token. API keys must use `MXS_API_KEY` or `--api-key`.
|
|
33
|
+
|
|
34
|
+
Credential renewal has two paths. If a stored OAuth `refresh_token` exists, the CLI uses a refresh-token grant. Device authorization normally stores a Better Auth session token; that path renews by calling Better Auth `/get-session`, accepting the refreshed `set-auth-token` header, and updating the stored session expiry.
|
|
35
|
+
|
|
36
|
+
## Configuration files
|
|
37
|
+
|
|
38
|
+
| File | Mode | Purpose |
|
|
39
|
+
| ------------------------------------- | ------ | -------------------------------------------------------- |
|
|
40
|
+
| `~/.config/mxs/profiles/<name>/config.json` | `0644` | API URL, API base, auth base, API version, client id. |
|
|
41
|
+
| `~/.config/mxs/profiles/<name>/credentials.json` | `0600` | Access token, refresh token, expiry, optional user. |
|
|
42
|
+
| `~/.config/mxs/current` | `0644` | Single line — the name of the active profile. |
|
|
43
|
+
|
|
44
|
+
`XDG_CONFIG_HOME` changes the base directory. Credential files with wider permissions are automatically changed to `0600`.
|
|
45
|
+
|
|
46
|
+
Example profile config:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"api_url": "https://blog.example.com",
|
|
51
|
+
"api_base": "https://blog.example.com/api/v3",
|
|
52
|
+
"auth_base": "https://blog.example.com/api/v3/auth",
|
|
53
|
+
"api_version": 3,
|
|
54
|
+
"client_id": "mxs-cli"
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Environment variables
|
|
59
|
+
|
|
60
|
+
| Variable | Meaning |
|
|
61
|
+
| ------------------ | ---------------------------------------------------------------------- |
|
|
62
|
+
| `MXS_API_URL` | API origin override. |
|
|
63
|
+
| `MXS_TOKEN` | Better Auth access token override; sent as `Authorization: Bearer`. |
|
|
64
|
+
| `MXS_API_KEY` | API key override; sent as `x-api-key`. |
|
|
65
|
+
| `MXS_PROFILE` | Profile name to use; equivalent to `--profile`. |
|
|
66
|
+
| `MXS_DEBUG=1` | Enables verbose HTTP diagnostics in auth helpers. |
|
|
67
|
+
| `EDITOR` | Editor for `post edit`, `note edit`, `page edit`, `config edit`. |
|
|
68
|
+
| `XDG_CONFIG_HOME` | Base directory for `mxs` config files. |
|
|
69
|
+
|
|
70
|
+
See `output-modes` for `--json`, `--output`, and the rest of the global flag table.
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: authoring
|
|
3
|
+
title: Content authoring (posts, notes, pages)
|
|
4
|
+
description: Drafting workflows, content sources, envelope precedence
|
|
5
|
+
order: 20
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Content authoring
|
|
9
|
+
|
|
10
|
+
Use this reference when drafting or modifying posts, notes, or pages.
|
|
11
|
+
|
|
12
|
+
## Resource selection
|
|
13
|
+
|
|
14
|
+
| Resource | Association | Publish commands | Envelope root |
|
|
15
|
+
| -------- | ----------- | --------------------------------- | ------------- |
|
|
16
|
+
| Post | Category | `post publish`, `post unpublish` | `<mxpost>` |
|
|
17
|
+
| Note | Topic | `note publish`, `note unpublish` | `<mxnote>` |
|
|
18
|
+
| Page | none | no dedicated publish command | `<mxpost>` |
|
|
19
|
+
|
|
20
|
+
## Preferred drafting sequence
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
┌─────────────────────────┐
|
|
24
|
+
│ Resolve category/topic │
|
|
25
|
+
└───────────┬─────────────┘
|
|
26
|
+
▼
|
|
27
|
+
┌─────────────────────────┐
|
|
28
|
+
│ Write LiteXML envelope │ (see litexml chapter)
|
|
29
|
+
└───────────┬─────────────┘
|
|
30
|
+
▼
|
|
31
|
+
┌─────────────────────────┐
|
|
32
|
+
│ Dry-run create/update │
|
|
33
|
+
└───────────┬─────────────┘
|
|
34
|
+
▼
|
|
35
|
+
┌─────────────────────────┐
|
|
36
|
+
│ Execute with --json │
|
|
37
|
+
└───────────┬─────────────┘
|
|
38
|
+
▼
|
|
39
|
+
┌─────────────────────────┐
|
|
40
|
+
│ Read back with llm/json │
|
|
41
|
+
└─────────────────────────┘
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Content sources
|
|
45
|
+
|
|
46
|
+
| Spec | Meaning |
|
|
47
|
+
| ----------------------------- | ------------------------------------------------ |
|
|
48
|
+
| `--content="inline literal"` | Use the argument as body text. |
|
|
49
|
+
| `--content=file=<path>` | Read body content from a file. |
|
|
50
|
+
| `--content=-` | Read body content from stdin. |
|
|
51
|
+
| `--content=stdin` | Read body content from stdin. |
|
|
52
|
+
| `--file <path>` | Read a LiteXML envelope with metadata and body. |
|
|
53
|
+
| `--file -` | Read a LiteXML envelope from stdin. |
|
|
54
|
+
|
|
55
|
+
`--meta`, `--images`, and comparable JSON fields accept either an inline JSON literal or `file=<path>`.
|
|
56
|
+
|
|
57
|
+
## Format rules
|
|
58
|
+
|
|
59
|
+
| Format | Behavior |
|
|
60
|
+
| ---------- | -------------------------------------------------------------------------------------------------------------- |
|
|
61
|
+
| `lexical` | Default. LiteXML is parsed through `@haklex/rich-litexml` and stored as Lexical JSON; derived plain text is also sent. |
|
|
62
|
+
| `markdown` | Content is sent as markdown text without Lexical conversion. |
|
|
63
|
+
|
|
64
|
+
For `lexical`, empty content is invalid when a content source is provided.
|
|
65
|
+
|
|
66
|
+
## Flag and envelope precedence
|
|
67
|
+
|
|
68
|
+
| Rule | Consequence |
|
|
69
|
+
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
70
|
+
| CLI flags override envelope metadata. | Use flags for last-mile corrections such as `--state draft`. |
|
|
71
|
+
| `update` preserves body when neither `--content` nor `--file` is supplied. | Use partial updates for metadata-only changes. |
|
|
72
|
+
| `edit` invokes `$EDITOR` when no content flags are supplied. | Avoid in non-interactive agent workflows unless explicitly requested. |
|
|
73
|
+
| Page file payloads use the post envelope parser. | Use `<mxpost>` for page envelopes. |
|
|
74
|
+
|
|
75
|
+
## Existing lexical content with rich nodes
|
|
76
|
+
|
|
77
|
+
Do not blindly round-trip an existing Lexical document through `--output xml` and `post update --file` when it contains links, embeds, or other rich nodes. A dry-run must prove that URLs and node-specific attributes survive conversion. If dry-run output shows empty link URLs or empty embed URLs, stop before writing; otherwise the update can silently damage the article structure.
|
|
78
|
+
|
|
79
|
+
When only the body needs to change, prefer `post update --content - --format lexical` with the extracted `<content>` body instead of `--file`; this avoids unintentionally patching envelope metadata such as tags or category.
|
|
80
|
+
|
|
81
|
+
## Post envelope
|
|
82
|
+
|
|
83
|
+
```xml
|
|
84
|
+
<mxpost>
|
|
85
|
+
<meta>
|
|
86
|
+
<title>Title</title>
|
|
87
|
+
<slug>stable-slug</slug>
|
|
88
|
+
<category>tech</category>
|
|
89
|
+
<tags>
|
|
90
|
+
<tag>ai</tag>
|
|
91
|
+
</tags>
|
|
92
|
+
<state>draft</state>
|
|
93
|
+
<summary>Short summary.</summary>
|
|
94
|
+
<format>lexical</format>
|
|
95
|
+
<copyright>true</copyright>
|
|
96
|
+
</meta>
|
|
97
|
+
<content>
|
|
98
|
+
<p>Paragraph.</p>
|
|
99
|
+
<h2>Section</h2>
|
|
100
|
+
<p>More content.</p>
|
|
101
|
+
</content>
|
|
102
|
+
</mxpost>
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Common commands:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
mxs post create --file ./post.xml --json
|
|
109
|
+
mxs post update stable-slug --title "New title" --state draft --json
|
|
110
|
+
mxs post publish stable-slug --json
|
|
111
|
+
mxs post get stable-slug --output llm
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Note envelope
|
|
115
|
+
|
|
116
|
+
```xml
|
|
117
|
+
<mxnote>
|
|
118
|
+
<meta>
|
|
119
|
+
<title>Daily Note</title>
|
|
120
|
+
<slug>daily-note</slug>
|
|
121
|
+
<topic>life</topic>
|
|
122
|
+
<state>draft</state>
|
|
123
|
+
<mood>calm</mood>
|
|
124
|
+
<weather>clear</weather>
|
|
125
|
+
<format>lexical</format>
|
|
126
|
+
</meta>
|
|
127
|
+
<content>
|
|
128
|
+
<p>Body.</p>
|
|
129
|
+
</content>
|
|
130
|
+
</mxnote>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Common commands:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
mxs note create --file ./note.xml --json
|
|
137
|
+
mxs note update daily-note --mood "focused" --json
|
|
138
|
+
mxs note publish daily-note --json
|
|
139
|
+
mxs note get daily-note --output llm
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Page envelope
|
|
143
|
+
|
|
144
|
+
Pages currently reuse the `<mxpost>` envelope shape. Page metadata supports `title`, `slug`, `subtitle`, `order`, `format`, and `meta`.
|
|
145
|
+
|
|
146
|
+
```xml
|
|
147
|
+
<mxpost>
|
|
148
|
+
<meta>
|
|
149
|
+
<title>About</title>
|
|
150
|
+
<slug>about</slug>
|
|
151
|
+
<subtitle>Profile and links</subtitle>
|
|
152
|
+
<order>10</order>
|
|
153
|
+
<format>lexical</format>
|
|
154
|
+
</meta>
|
|
155
|
+
<content>
|
|
156
|
+
<p>Page body.</p>
|
|
157
|
+
</content>
|
|
158
|
+
</mxpost>
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
mxs page create --file ./page.xml --json
|
|
163
|
+
mxs page update about --subtitle "Updated subtitle" --json
|
|
164
|
+
mxs page get about --output llm
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Read-back verification
|
|
168
|
+
|
|
169
|
+
| Resource | Minimum read-back checks |
|
|
170
|
+
| -------- | --------------------------------------------------------------------------------------- |
|
|
171
|
+
| Post | `title`, `slug`, `state`, category, tags, summary, representative body text. |
|
|
172
|
+
| Note | `title`, `slug` or `nid`, `state`, topic, metadata fields, representative body text. |
|
|
173
|
+
| Page | `title`, `slug`, `subtitle`, `order`, representative body text. |
|
|
174
|
+
|
|
175
|
+
Prefer `--output llm` for low-noise body inspection and `--json` for strict field checks.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-auth
|
|
3
|
+
title: Auth commands
|
|
4
|
+
description: auth login/logout/whoami/status
|
|
5
|
+
order: 37
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Auth commands
|
|
9
|
+
|
|
10
|
+
| Command | Purpose | Notes |
|
|
11
|
+
| ------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
12
|
+
| `mxs auth login` | Start device authorization flow and store credentials. | In interactive non-JSON mode, attempts to open verification URL. |
|
|
13
|
+
| `mxs auth logout` | Delete stored credentials. | Does not delete server-side sessions. |
|
|
14
|
+
| `mxs auth whoami` | Show authenticated user and resolved API URL. | Use before mutation target confirmation. |
|
|
15
|
+
| `mxs auth status` | Show token presence, expiry, refresh-token availability, and user data. | Use before write workflows. |
|
|
16
|
+
|
|
17
|
+
`auth status` reads local CLI state. `auth whoami` validates bearer credentials against the configured server when a session token is available, then falls back to cached identity only when the server returns no session. It still does not prove write authorization; a target may allow authenticated identity reads while returning `auth.expired` or `auth.denied` for mutations. Treat the first real mutation, or a server-validated write-permission probe, as the authoritative write-auth check.
|
|
18
|
+
|
|
19
|
+
See `auth-config` for profiles, env vars, and target selection.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-category
|
|
3
|
+
title: Category commands
|
|
4
|
+
description: category list/get/create/update/delete syntax
|
|
5
|
+
order: 34
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Category commands
|
|
9
|
+
|
|
10
|
+
| Command | Purpose | Flags |
|
|
11
|
+
| -------------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
|
|
12
|
+
| `mxs category list` | List categories and tags. | global flags |
|
|
13
|
+
| `mxs category get <slugOrId>` | Read a category or tag. | global flags |
|
|
14
|
+
| `mxs category create` | Create a category or tag. | required: `--name <s>`, `--slug <s>`; optional: `--type <s>`, `--icon <s>` |
|
|
15
|
+
| `mxs category update <slugOrId>` | Patch category or tag fields. | `--name <s>`, `--slug <s>`, `--type <s>`, `--icon <s>` |
|
|
16
|
+
| `mxs category delete <slugOrId>` | Delete a category or tag. | `--force`; prefer `--dry-run` first |
|
|
17
|
+
|
|
18
|
+
`--type` accepts `category` or `tag` and maps to the server category type.
|
|
19
|
+
|
|
20
|
+
Dry-run support: `create`, `update`, `delete`.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-comment
|
|
3
|
+
title: Comment commands
|
|
4
|
+
description: comment list/get/approve/reject/delete + moderation safety
|
|
5
|
+
order: 33
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Comment commands
|
|
9
|
+
|
|
10
|
+
Moderation surface for the comment queue. State codes: `unread=0`, `read=1`, `junk=2`. The CLI accepts the *names* (`unread`, `read`, `junk`) on `--state`. Single-id verbs and `--all` invocations all route through the server's batch endpoints (`PATCH /comments/batch/state`, `DELETE /comments/batch`) — there is one unified code path.
|
|
11
|
+
|
|
12
|
+
| Command | Purpose | Principal flags |
|
|
13
|
+
| ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------ |
|
|
14
|
+
| `mxs comment list` | List comments. | `--page <n>`, `--size <n>`, `--state <unread\|read\|junk>` (default `unread`), `--all` |
|
|
15
|
+
| `mxs comment unread` | Shortcut for `comment list --state unread`. | `--page <n>`, `--size <n>` |
|
|
16
|
+
| `mxs comment get <id>` | Show a single comment by id. | `--json`, `--output readable` |
|
|
17
|
+
| `mxs comment approve <id...>` | Mark comments as read (state=1). | `--all`, `--state <s>`, `--force` |
|
|
18
|
+
| `mxs comment reject <id...>` | Mark comments as junk (state=2). | `--all`, `--state <s>`, `--force` |
|
|
19
|
+
| `mxs comment delete <id...>` | Soft-delete comments. | `--all`, `--state <s>`, `--force` |
|
|
20
|
+
|
|
21
|
+
## Comment list flags
|
|
22
|
+
|
|
23
|
+
| Flag | Meaning |
|
|
24
|
+
| --------------------------------- | -------------------------------------------------------------------- |
|
|
25
|
+
| `--page <n>` | Page number. |
|
|
26
|
+
| `--size <n>` | Page size. |
|
|
27
|
+
| `--state <unread\|read\|junk>` | Filter by state. Default `unread`. |
|
|
28
|
+
| `--all` | Aggregate every state into one response (three parallel requests; pagination is collapsed). |
|
|
29
|
+
|
|
30
|
+
## Comment moderation flags
|
|
31
|
+
|
|
32
|
+
| Flag | Applies to | Effect |
|
|
33
|
+
| ---------------- | --------------------------------------- | ------------------------------------------------------------------- |
|
|
34
|
+
| `<id...>` | approve, reject, delete | One or more comment ids. Mutually exclusive with `--all`. |
|
|
35
|
+
| `--all` | approve, reject, delete | Apply to every comment, optionally filtered by `--state` as `currentState`. |
|
|
36
|
+
| `--state <s>` | approve, reject, delete with `--all` | Restrict the affected set to comments currently in that state. |
|
|
37
|
+
| `--force` | delete (single id), any `--all` | Required in non-TTY contexts to confirm destructive operations. |
|
|
38
|
+
|
|
39
|
+
## Comment safety guards
|
|
40
|
+
|
|
41
|
+
| Operation | TTY | Non-TTY |
|
|
42
|
+
| ------------------------------------------------------------ | ------- | -------------------------------------- |
|
|
43
|
+
| `approve <id...>` / `reject <id...>` | Direct. | Direct (state changes are soft and reversible). |
|
|
44
|
+
| `delete <id...>` (single or multi) | Direct. | Requires `--force`. |
|
|
45
|
+
| `approve --all` / `reject --all` / `delete --all` | Direct. | Requires `--force`. |
|
|
46
|
+
|
|
47
|
+
Dry-run support: `approve`, `reject`, `delete` (single id or `--all`).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-config
|
|
3
|
+
title: Config commands
|
|
4
|
+
description: server-side options — config list/get/set/edit
|
|
5
|
+
order: 36
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Config commands
|
|
9
|
+
|
|
10
|
+
`config` reads and writes the live `/options` document on the server. These affect server behavior — confirm intent before mutating.
|
|
11
|
+
|
|
12
|
+
| Command | Purpose | Flags |
|
|
13
|
+
| -------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------- |
|
|
14
|
+
| `mxs config list` | Read all server options from `/options`. | global flags |
|
|
15
|
+
| `mxs config get <key>` | Read one server option. | global flags |
|
|
16
|
+
| `mxs config set <key> <value>` | Patch one server option. | `--type json\|string\|number\|bool` |
|
|
17
|
+
| `mxs config edit` | Open all options in `$EDITOR`, then patch changed JSON values. | supports `--dry-run` |
|
|
18
|
+
|
|
19
|
+
Without `--type`, `config set` attempts JSON parsing first and falls back to string.
|
|
20
|
+
|
|
21
|
+
Dry-run support: `set`, `edit`.
|
|
22
|
+
|
|
23
|
+
## Read-back
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
mxs config get <key> --json
|
|
27
|
+
mxs config list --json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Verify only the intended option changed.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-note
|
|
3
|
+
title: Note commands
|
|
4
|
+
description: note list/get/create/edit/update/delete/publish/unpublish syntax
|
|
5
|
+
order: 31
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Note commands
|
|
9
|
+
|
|
10
|
+
| Command | Purpose | Principal flags |
|
|
11
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------- |
|
|
12
|
+
| `mxs note list` | List notes. | `--page <n>`, `--size <n>`, `--state <s>`, `--sort <s>` |
|
|
13
|
+
| `mxs note get <slugOrId>` | Read by Snowflake id, numeric nid, or direct identifier. | `--json`, `--output readable\|llm\|xml` |
|
|
14
|
+
| `mxs note create` | Create a note. | note write flags |
|
|
15
|
+
| `mxs note edit <slugOrId>` | Edit via `$EDITOR` when no content flags are supplied; otherwise replace through flags or file. | note write flags |
|
|
16
|
+
| `mxs note update <slugOrId>` | Patch selected fields. Content remains unchanged unless `--content` or `--file` is supplied. | note write flags |
|
|
17
|
+
| `mxs note delete <slugOrId>` | Delete a note. | `--force`; prefer `--dry-run` first |
|
|
18
|
+
| `mxs note publish <slugOrId>` | Set `isPublished=true`. | supports `--dry-run` |
|
|
19
|
+
| `mxs note unpublish <slugOrId>` | Set `isPublished=false`. | supports `--dry-run` |
|
|
20
|
+
|
|
21
|
+
## Note list flags
|
|
22
|
+
|
|
23
|
+
| Flag | Meaning |
|
|
24
|
+
| -------------- | -------------------------------------------------------- |
|
|
25
|
+
| `--page <n>` | Page number. |
|
|
26
|
+
| `--size <n>` | Page size. |
|
|
27
|
+
| `--state <s>` | Publication filter. |
|
|
28
|
+
| `--sort <s>` | Sort field passed as `sortBy`. |
|
|
29
|
+
|
|
30
|
+
Compatibility note: verify the live note list query contract before using `--state`; do not assume post and note list filters accept the same value shape.
|
|
31
|
+
|
|
32
|
+
## Note write flags
|
|
33
|
+
|
|
34
|
+
| Flag | Field or behavior |
|
|
35
|
+
| ----------------------- | ---------------------------------------------------------------- |
|
|
36
|
+
| `--title <s>` | `title`; create defaults to `无题` when omitted. |
|
|
37
|
+
| `--slug <s>` | `slug` |
|
|
38
|
+
| `--topic <s>` | Topic id, slug, or name; resolved to `topicId`. |
|
|
39
|
+
| `--content <spec>` | Body source; see `authoring`. |
|
|
40
|
+
| `--format <s>` | `lexical` or `markdown`; default is `lexical`. |
|
|
41
|
+
| `--state <s>` | `publish` or `draft`; maps to `isPublished`. |
|
|
42
|
+
| `--mood <s>` | `mood` |
|
|
43
|
+
| `--weather <s>` | `weather` |
|
|
44
|
+
| `--public-at <iso>` | `publicAt` |
|
|
45
|
+
| `--password <s>` | `password` |
|
|
46
|
+
| `--bookmark <b>` | `true` or `false`. |
|
|
47
|
+
| `--coords <s>` | `lat,lng`; maps to `{ latitude, longitude }`. |
|
|
48
|
+
| `--location <s>` | `location` |
|
|
49
|
+
| `--images <spec>` | JSON literal or `file=<path>`. |
|
|
50
|
+
| `--meta <spec>` | JSON literal or `file=<path>`. |
|
|
51
|
+
| `--file <path>` | LiteXML envelope. |
|
|
52
|
+
|
|
53
|
+
Dry-run support: `create`, `edit`, `update`, `delete`, `publish`, `unpublish`.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-page
|
|
3
|
+
title: Page commands
|
|
4
|
+
description: page list/get/create/edit/update/delete syntax
|
|
5
|
+
order: 32
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Page commands
|
|
9
|
+
|
|
10
|
+
| Command | Purpose | Principal flags |
|
|
11
|
+
| ---------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------- |
|
|
12
|
+
| `mxs page list` | List pages. | global flags |
|
|
13
|
+
| `mxs page get <slugOrId>` | Read by Snowflake id or slug. | `--json`, `--output readable\|llm\|xml` |
|
|
14
|
+
| `mxs page create` | Create a page. | page write flags |
|
|
15
|
+
| `mxs page edit <slugOrId>` | Edit via `$EDITOR` when no content flags are supplied; otherwise replace through flags or file. | page write flags |
|
|
16
|
+
| `mxs page update <slugOrId>` | Patch selected fields. Content remains unchanged unless `--content` or `--file` is supplied. | page write flags |
|
|
17
|
+
| `mxs page delete <slugOrId>` | Delete a page. | `--force`; prefer `--dry-run` first |
|
|
18
|
+
|
|
19
|
+
## Page write flags
|
|
20
|
+
|
|
21
|
+
| Flag | Field or behavior |
|
|
22
|
+
| --------------------- | -------------------------------------------------------------- |
|
|
23
|
+
| `--title <s>` | `title` |
|
|
24
|
+
| `--slug <s>` | `slug` |
|
|
25
|
+
| `--subtitle <s>` | `subtitle` |
|
|
26
|
+
| `--order <n>` | Numeric page order. |
|
|
27
|
+
| `--content <spec>` | Body source; see `authoring`. |
|
|
28
|
+
| `--format <s>` | `lexical` or `markdown`; default is `lexical`. |
|
|
29
|
+
| `--meta <spec>` | JSON literal or `file=<path>`. |
|
|
30
|
+
| `--file <path>` | LiteXML envelope. Pages currently reuse `<mxpost>`. |
|
|
31
|
+
|
|
32
|
+
Dry-run support: `create`, `edit`, `update`, `delete`.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-post
|
|
3
|
+
title: Post commands
|
|
4
|
+
description: post list/get/create/edit/update/delete/publish/unpublish syntax
|
|
5
|
+
order: 30
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Post commands
|
|
9
|
+
|
|
10
|
+
| Command | Purpose | Principal flags |
|
|
11
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------- |
|
|
12
|
+
| `mxs post list` | List posts. | `--page <n>`, `--size <n>`, `--state <s>`, `--sort <s>` |
|
|
13
|
+
| `mxs post get <slugOrId>` | Read a post by Snowflake id or slug. | `--json`, `--output readable\|llm\|xml` |
|
|
14
|
+
| `mxs post create` | Create a post. | post write flags |
|
|
15
|
+
| `mxs post edit <slugOrId>` | Edit via `$EDITOR` when no content flags are supplied; otherwise replace through flags or file. | post write flags |
|
|
16
|
+
| `mxs post update <slugOrId>` | Patch selected fields. Content remains unchanged unless `--content` or `--file` is supplied. | post write flags |
|
|
17
|
+
| `mxs post delete <slugOrId>` | Delete a post. | `--force`; prefer `--dry-run` first |
|
|
18
|
+
| `mxs post publish <slugOrId>` | Set `isPublished=true`. | supports `--dry-run` |
|
|
19
|
+
| `mxs post unpublish <slugOrId>` | Set `isPublished=false`. | supports `--dry-run` |
|
|
20
|
+
|
|
21
|
+
## Post list flags
|
|
22
|
+
|
|
23
|
+
| Flag | Meaning |
|
|
24
|
+
| -------------- | -------------------------------------------------------- |
|
|
25
|
+
| `--page <n>` | Page number. |
|
|
26
|
+
| `--size <n>` | Page size. |
|
|
27
|
+
| `--state <s>` | Publication filter, commonly `draft` or `publish`. |
|
|
28
|
+
| `--sort <s>` | Sort field, commonly `created` or `modified`. |
|
|
29
|
+
|
|
30
|
+
Compatibility note: `post list --state publish` may be rejected by the server as an invalid numeric `state`. Prefer omitting `--state` when listing through an anonymous or read-only context, or verify the live API contract before relying on this filter. `--sort created` is forwarded as `sortBy=created`; the server-side repository maps `createdAt`, `modifiedAt`, and `pinAt`, so verify ordering before treating the first row as latest.
|
|
31
|
+
|
|
32
|
+
## Post write flags
|
|
33
|
+
|
|
34
|
+
| Flag | Field or behavior |
|
|
35
|
+
| ----------------------- | ---------------------------------------------------------------- |
|
|
36
|
+
| `--title <s>` | `title` |
|
|
37
|
+
| `--slug <s>` | `slug` |
|
|
38
|
+
| `--category <s>` | Category id, slug, or name; resolved to `categoryId`. |
|
|
39
|
+
| `--content <spec>` | Body source; see `authoring`. |
|
|
40
|
+
| `--format <s>` | `lexical` or `markdown`; default is `lexical`. |
|
|
41
|
+
| `--summary <s>` | `summary` |
|
|
42
|
+
| `--state <s>` | `publish` or `draft`; maps to `isPublished`. |
|
|
43
|
+
| `--tags <csv>` | Comma-separated tags. |
|
|
44
|
+
| `--copyright <b>` | `true` or `false`. |
|
|
45
|
+
| `--pin <iso>` | Pin timestamp or date. |
|
|
46
|
+
| `--pin-order <n>` | Numeric pin order. |
|
|
47
|
+
| `--related <csv>` | Comma-separated related document ids. |
|
|
48
|
+
| `--meta <spec>` | JSON literal or `file=<path>`. |
|
|
49
|
+
| `--file <path>` | LiteXML envelope. |
|
|
50
|
+
|
|
51
|
+
Dry-run support: `create`, `edit`, `update`, `delete`, `publish`, `unpublish`.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-preview
|
|
3
|
+
title: Preview command
|
|
4
|
+
description: render LiteXML / envelope to HTML and open it in a browser
|
|
5
|
+
order: 39
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Preview command
|
|
9
|
+
|
|
10
|
+
`mxs preview` renders a LiteXML fragment or `<mxpost>` / `<mxnote>` envelope to HTML and (by default) opens it in the system browser. It is a thin wrapper around the `@haklex/rich-litexml-cli` `litexml --format html` pipeline, so the output matches what the editor would render once published.
|
|
11
|
+
|
|
12
|
+
| Command | Behavior |
|
|
13
|
+
| ---------------------------------------- | --------------------------------------------------------------------------- |
|
|
14
|
+
| `mxs preview <file>` | Render the file and open the preview in a browser. |
|
|
15
|
+
| `mxs preview -` | Read LiteXML or envelope from stdin and open the preview. |
|
|
16
|
+
| `mxs preview <file> --print` | Emit HTML to stdout instead of opening a browser. |
|
|
17
|
+
| `mxs preview <file> --save <out.html>` | Write HTML to `<out.html>` instead of opening a browser. |
|
|
18
|
+
|
|
19
|
+
## Flags
|
|
20
|
+
|
|
21
|
+
| Flag | Meaning |
|
|
22
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
|
|
23
|
+
| `--theme <light\|dark>` | HTML theme. Default `light`. |
|
|
24
|
+
| `--variant <article\|note\|comment>` | HTML variant. Auto-detected from the envelope root (`<mxpost>` → `article`, `<mxnote>` → `note`). |
|
|
25
|
+
| `--save <path>` | Write HTML to a file instead of opening the browser. Mutually exclusive with `--print`. |
|
|
26
|
+
| `--print` | Emit HTML to stdout. Mutually exclusive with `--save`. |
|
|
27
|
+
|
|
28
|
+
## Behavior notes
|
|
29
|
+
|
|
30
|
+
- Input format is auto-detected. If the input starts with `<mxpost>` or `<mxnote>`, the envelope is parsed and only the `<content>` body is rendered (envelope `<meta>` such as title, category, tags is **not** reflected in the HTML preview — this command is for visualising the article body, not the listing card).
|
|
31
|
+
- For raw LiteXML fragments (no envelope wrapper), the entire input is treated as the article body.
|
|
32
|
+
- Variant detection only fires when an envelope is supplied. Override with `--variant` when previewing a raw fragment that should render as a note or comment.
|
|
33
|
+
- The command does not contact the `mx-core` server and does not require an active profile.
|
|
34
|
+
|
|
35
|
+
## Examples
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# Open envelope file in browser
|
|
39
|
+
mxs preview ./post.xml
|
|
40
|
+
|
|
41
|
+
# Pipe from another tool
|
|
42
|
+
some-generator | mxs preview -
|
|
43
|
+
|
|
44
|
+
# Dark theme, save to file
|
|
45
|
+
mxs preview ./note.xml --theme dark --save ./preview.html
|
|
46
|
+
|
|
47
|
+
# Emit HTML to stdout (e.g. for CI)
|
|
48
|
+
mxs preview ./post.xml --print > preview.html
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Failure modes
|
|
52
|
+
|
|
53
|
+
| Symptom | Likely cause |
|
|
54
|
+
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
55
|
+
| `cannot resolve @haklex/rich-litexml-cli binary` | Installed dep is broken; reinstall `@mx-space/cli` or run `pnpm install`. |
|
|
56
|
+
| `Cannot resolve @haklex/rich-compose asset "style.css"` | Outdated `@haklex/rich-compose` (< 0.15.2). Upgrade or reinstall. |
|
|
57
|
+
| `expected root <mxpost>` / `expected root <mxnote>` | Input begins with the wrong envelope root, or the envelope is malformed. Check the root tag. |
|
|
58
|
+
| Browser does not open | `--open` shells out to the system `open`/`xdg-open`/`start`. Use `--save` or `--print` instead. |
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-profile
|
|
3
|
+
title: Profile commands
|
|
4
|
+
description: local CLI profiles — profile ls/show/use/mark/rm
|
|
5
|
+
order: 38
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Profile commands
|
|
9
|
+
|
|
10
|
+
Profiles are stored under `~/.config/mxs/profiles/<name>/` and let one workstation talk to multiple `mx-core` deployments. The currently active profile is recorded in `~/.config/mxs/current`.
|
|
11
|
+
|
|
12
|
+
| Command | Purpose |
|
|
13
|
+
| ---------------------------------------------------- | -------------------------------------------------- |
|
|
14
|
+
| `mxs profile ls` | List all known profiles. |
|
|
15
|
+
| `mxs profile show [<name>]` | Show one profile (defaults to active). |
|
|
16
|
+
| `mxs profile use <name>` | Switch the active profile. |
|
|
17
|
+
| `mxs profile mark <name> [--production\|--no-production]` | Flag a profile as production or non-production. |
|
|
18
|
+
| `mxs profile rm <name> [--force]` | Delete a profile. |
|
|
19
|
+
|
|
20
|
+
A profile flagged as production triggers an additional write guard — mutations require an explicit `--profile <name>` argument (the `profile.write_requires_explicit` error). This avoids accidental writes to production from a current-profile slip.
|
|
21
|
+
|
|
22
|
+
See `auth-config` for env vars and target selection rules.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: commands-topic
|
|
3
|
+
title: Topic commands
|
|
4
|
+
description: topic list/get/create/update/delete syntax
|
|
5
|
+
order: 35
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Topic commands
|
|
9
|
+
|
|
10
|
+
| Command | Purpose | Flags |
|
|
11
|
+
| ----------------------------- | -------------------------------------- | ---------------------------------------------------------------------- |
|
|
12
|
+
| `mxs topic list` | List all topics. | global flags |
|
|
13
|
+
| `mxs topic get <slugOrId>` | Read a topic by Snowflake id or slug. | global flags |
|
|
14
|
+
| `mxs topic create` | Create a topic. | required: `--name <s>`, `--slug <s>`; optional: `--description <s>`, `--icon <s>` |
|
|
15
|
+
| `mxs topic update <slugOrId>` | Patch topic fields. | `--name <s>`, `--slug <s>`, `--description <s>`, `--icon <s>` |
|
|
16
|
+
| `mxs topic delete <slugOrId>` | Delete a topic. | `--force`; prefer `--dry-run` first |
|
|
17
|
+
|
|
18
|
+
Dry-run support: `create`, `update`, `delete`.
|