@plaiful/cli 0.6.0 → 0.7.0

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.
Files changed (3) hide show
  1. package/README.md +134 -130
  2. package/package.json +21 -21
  3. package/src/cli.js +1205 -1120
package/README.md CHANGED
@@ -1,130 +1,134 @@
1
- # The Plaiful CLI
2
-
3
- > `plaiful` is how your team, or your coding agent, works on your Plaiful product from your game's repo. **Part 1**
4
- > is for the people on your team. **Part 2** is for your coding agent: every command.
5
-
6
- ## Part 1: for your team
7
-
8
- ### What it is
9
-
10
- - A command-line tool for your Plaiful product: you type commands in a terminal, in your game's repo.
11
- - It loads your data into Plaiful, reads back what Plaiful has, and reads the platform docs.
12
- - It signs in as your CMS account, so it can only see and change your own products.
13
- - It needs no AWS access.
14
- - It works in your development environment. Staging and production get your content when you promote.
15
-
16
- ### Install it and sign in
17
-
18
- You need Node 18 or later.
19
-
20
- ```sh
21
- npm install -g @plaiful/cli
22
- plaiful login
23
- ```
24
-
25
- - `plaiful login` opens the CMS. Check the code matches, and approve. The sign-in lasts 12 hours.
26
- - You need to be on Plaiful's allowlist, and own your product or have it shared with you.
27
-
28
- ### What you'll use it for
29
-
30
- | To | Run |
31
- |---|---|
32
- | Get your game's repo | `plaiful clone <product>`, or `plaiful init <product>` in a repo you already have |
33
- | Get your product's settings | `plaiful docs pull` |
34
- | Read the docs | `plaiful docs`, `plaiful docs search <words>` |
35
- | Load your world into Plaiful | `plaiful seed world`, then `plaiful seed world --apply` (and `lore`, `map`, `personas`) |
36
- | See what Plaiful has | `plaiful status`, `plaiful quests`, `plaiful lore`, `plaiful world`, `plaiful assets` |
37
- | Publish your OVID declaration | `plaiful ovid check`, then `plaiful ovid publish` |
38
- | Deploy and run worker agents | `plaiful agents deploy`, `plaiful agents run <name>` |
39
-
40
- Every load starts as a dry run: it shows what would change, and changes nothing until you add `--apply`.
41
-
42
- ### Keys for coding agents and CI
43
-
44
- - A coding agent working on its own, or a CI job, can use a key instead of a sign-in.
45
- - Your product's owner makes one in the CMS: **DevOps → Deployment → your product → CLI keys**.
46
- - A key works on one product, for the jobs you pick, and stops the moment you revoke it.
47
- - Keep it out of your repo.
48
-
49
- ## Part 2: for your coding agent
50
-
51
- Every command runs as the signed-in CMS account (or a product API key that account issued), on that account's
52
- products, in **dev**.
53
-
54
- ### Commands
55
-
56
- ```sh
57
- plaiful login # opens the CMS: check the code matches, approve. 12 hours.
58
- plaiful clone roadforge # clone the game repo, write .env.development, docs pull, npm install, open Zed
59
- plaiful init roadforge # (a repo you already have) writes .plaiful.json (commit it; no secrets) and makes the resources/ folders
60
- plaiful docs # the platform docs, live (docs read <doc>, docs search <words>, docs changes)
61
- plaiful docs pull # your client-config.md into docs/plaiful/ (--copies: local copies of the docs too)
62
- plaiful mcp # the docs as MCP tools for your coding assistant: claude mcp add plaiful -- plaiful mcp
63
- plaiful env # rewrite .env.development from the dev client config (keeps your own lines)
64
- plaiful ovid check # checks docs/plaiful/roadforge-ovid-declaration.json
65
- plaiful ovid publish # checks it again and publishes it; OVID reads it within ~5 minutes
66
- plaiful ovid show # what OVID has now
67
- plaiful seed world # dry run: what resources/world/roadforge/*.json make, and what changes in dev
68
- plaiful seed world --apply # write it (then lore, then map); --reset also puts the clock, reveals and NPC bindings back
69
- plaiful seed personas # THESPIS personas and situations from resources/personas/roadforge/ (same dry run / --apply)
70
- plaiful status # what OVID and THESPIS have in dev: counts per store, the clock, the declaration
71
- plaiful assets # per agent: records, and how many have art made / pending / failed / none yet
72
- plaiful assets crew-portrait --state failed # one agent's records: state, why a render failed, where the files are
73
- plaiful quests # the quests OVID wrote: steps, and what each pays (--track, --series); quests show <id>
74
- plaiful lore # the lore sets (lore show <setId>: a set's snippets)
75
- plaiful world # the world's states and events in story order, and the clock
76
- plaiful agents # your product's SmartBuilder agents in dev (agents show <name>: one agent's config)
77
- plaiful agents deploy # deploy or redeploy every config in resources/agents/roadforge/ (or name the files)
78
- plaiful agents run crew-portrait role=medic # make one record (placeholder values as key=value)
79
- plaiful agents batch crew-portrait --count 20 # start a batch (or a batch body file) → a job id
80
- plaiful agents status crew-portrait <jobId> # a batch's progress
81
- plaiful records import crew-portrait # dry run: records you wrote (resources/records/roadforge/crew-portrait.json)
82
- # into the agent's table; --apply writes them, --no-render skips the art
83
- plaiful lists # the product's SSM lists
84
- plaiful lists set shop_type tavern blacksmith healer # write one (lists get shop_type reads it)
85
- plaiful midas pricing # what each quest pays, in your reward kinds (MIDAS); delivered in the quest's rewards
86
- plaiful midas pricing set scrap --base 20 --per-effort 10 # price a kind (unset <kind>, weight <step> <n>, apply [file])
87
- plaiful upload ovid-map-biomes-tiles.json ovid-map-kingdoms-tiles.json ovid-map-colors.json # map tiles → map-data/
88
- plaiful whoami # who you are (or which key), and your products
89
- plaiful logout
90
- ```
91
-
92
- `plaiful help` lists every command and option.
93
-
94
- ### Notes
95
-
96
- - `--json` on any command prints the platform's answer as JSON (for agents). Exit codes: `0` done, `1` the platform
97
- said no (invalid, not allowed, not signed in), `2` the command itself was wrong.
98
- - Everything works in **dev**. Staging and prod get your content through Plaiful's promotion.
99
- - `docs pull` keeps `client-config.md` (your keys) out of git with `docs/plaiful/.gitignore`, and prints the
100
- `git rm --cached` line if it was committed before.
101
- - `clone` needs access to the repo on GitHub (git signed in: `gh auth login` or Git Credential Manager), and
102
- `npm install` needs npm access to the `@plaiful` packages. It writes `.env.development` only when the repo has the
103
- web template's `.env.development.example`.
104
- - `lists set` writes a StringList in your product's namespace. It won't touch a key (SecureString), a setting (a plain
105
- String), or `access/*` (who may play).
106
- - The sign-in is kept in `~/.plaiful/credentials`, never in the repo. `PLAIFUL_API_URL` or `--api` points at another API.
107
- - You need to be on the Plaiful allowlist, and own or be shared the product (Plaiful staff: every product).
108
- - From a PlaifulCMS checkout instead of npm: `npm install -g <path to PlaifulCMS>/packages/plaiful-cli`. The package
109
- is public on npmjs.com; it holds no secrets, and everything it does needs a CMS sign-in or a key.
110
-
111
- ### Keys for agents and CI
112
-
113
- A product's owner issues keys in the CMS: Product deployment → the product → **CLI keys**. A key is shown once; set
114
- it as `PLAIFUL_TOKEN` in CI or the agent's environment (never in the repo) and the CLI uses it instead of a sign-in:
115
-
116
- ```sh
117
- PLAIFUL_TOKEN=plf_k_… plaiful seed world --apply
118
- ```
119
-
120
- A key acts as the owner who issued it, on that one product, in dev, for the scopes picked (`docs`, `status`, `seed`,
121
- `ovid:publish`, `lists`, `upload`). Revoking it in the CMS stops it at once; so does its issuer losing the product. The
122
- same screen shows the product's activity: everything the CLI and its keys did.
123
-
124
- ### For Plaiful staff
125
-
126
- - **Design:** `docs/system/product/PARTNER_API_AND_CLI.md`.
127
- - **Publishing a new version:** bump `version` in `package.json`, then `npm publish` from this folder, signed in to
128
- npm as a member of the `plaiful` org.
129
- - **Tests:** the end-to-end tests run this CLI against the partner API handler:
130
- `lambda/functions/partner-api/__tests__/partner-api.test.js`.
1
+ # The Plaiful CLI
2
+
3
+ > `plaiful` is how your team, or your coding agent, works on your Plaiful product from your game's repo. **Part 1**
4
+ > is for the people on your team. **Part 2** is for your coding agent: every command.
5
+
6
+ ## Part 1: for your team
7
+
8
+ ### What it is
9
+
10
+ - A command-line tool for your Plaiful product: you type commands in a terminal, in your game's repo.
11
+ - It loads your data into Plaiful, reads back what Plaiful has, and reads the platform docs.
12
+ - It signs in as your CMS account, so it can only see and change your own products.
13
+ - It needs no AWS access.
14
+ - It works in your development environment. Staging and production get your content when you promote.
15
+
16
+ ### Install it and sign in
17
+
18
+ You need Node 18 or later.
19
+
20
+ ```sh
21
+ npm install -g @plaiful/cli
22
+ plaiful login
23
+ ```
24
+
25
+ - `plaiful login` opens the CMS. Check the code matches, and approve. The sign-in lasts 12 hours.
26
+ - You need to be on Plaiful's allowlist, and own your product or have it shared with you.
27
+
28
+ ### What you'll use it for
29
+
30
+ | To | Run |
31
+ |---|---|
32
+ | Get your game's repo | `plaiful clone <product>`, or `plaiful init <product>` in a repo you already have |
33
+ | Get your product's settings | `plaiful docs pull` |
34
+ | Read the docs | `plaiful docs`, `plaiful docs search <words>` |
35
+ | Load your world into Plaiful | `plaiful seed world`, then `plaiful seed world --apply` (and `lore`, `map`, `personas`) |
36
+ | See what Plaiful has | `plaiful status`, `plaiful quests`, `plaiful lore`, `plaiful world`, `plaiful assets` |
37
+ | Get a cinematic script for a world event | `plaiful events script write <eventId> --wait`, then `plaiful events script export <eventId> --fountain` |
38
+ | Publish your OVID declaration | `plaiful ovid check`, then `plaiful ovid publish` |
39
+ | Deploy and run worker agents | `plaiful agents deploy`, `plaiful agents run <name>` |
40
+
41
+ Every load starts as a dry run: it shows what would change, and changes nothing until you add `--apply`.
42
+
43
+ ### Keys for coding agents and CI
44
+
45
+ - A coding agent working on its own, or a CI job, can use a key instead of a sign-in.
46
+ - Your product's owner makes one in the CMS: **DevOps → Deployment → your product → CLI keys**.
47
+ - A key works on one product, for the jobs you pick, and stops the moment you revoke it.
48
+ - Keep it out of your repo.
49
+
50
+ ## Part 2: for your coding agent
51
+
52
+ Every command runs as the signed-in CMS account (or a product API key that account issued), on that account's
53
+ products, in **dev**.
54
+
55
+ ### Commands
56
+
57
+ ```sh
58
+ plaiful login # opens the CMS: check the code matches, approve. 12 hours.
59
+ plaiful clone roadforge # clone the game repo, write .env.development, docs pull, npm install, open Zed
60
+ plaiful init roadforge # (a repo you already have) writes .plaiful.json (commit it; no secrets) and makes the resources/ folders
61
+ plaiful docs # the platform docs, live (docs read <doc>, docs search <words>, docs changes)
62
+ plaiful docs pull # your client-config.md into docs/plaiful/ (--copies: local copies of the docs too)
63
+ plaiful mcp # the docs as MCP tools for your coding assistant: claude mcp add plaiful -- plaiful mcp
64
+ plaiful env # rewrite .env.development from the dev client config (keeps your own lines)
65
+ plaiful ovid check # checks docs/plaiful/roadforge-ovid-declaration.json
66
+ plaiful ovid publish # checks it again and publishes it; OVID reads it within ~5 minutes
67
+ plaiful ovid show # what OVID has now
68
+ plaiful seed world # dry run: what resources/world/roadforge/*.json make, and what changes in dev
69
+ plaiful seed world --apply # write it (then lore, then map); --reset also puts the clock, reveals and NPC bindings back
70
+ plaiful seed personas # THESPIS personas and situations from resources/personas/roadforge/ (same dry run / --apply)
71
+ plaiful status # what OVID and THESPIS have in dev: counts per store, the clock, the declaration
72
+ plaiful assets # per agent: records, and how many have art made / pending / failed / none yet
73
+ plaiful assets crew-portrait --state failed # one agent's records: state, why a render failed, where the files are
74
+ plaiful quests # the quests OVID wrote: steps, and what each pays (--track, --series); quests show <id>
75
+ plaiful lore # the lore sets (lore show <setId>: a set's snippets)
76
+ plaiful world # the world's states and events in story order, and the clock
77
+ plaiful events script write y1-s2-m1-the-object-ev-the-recovery --wait # OVID writes the event's cinematic (a draft)
78
+ plaiful events script get y1-s2-m1-the-object-ev-the-recovery # the screenplay page, the versions, Soter's flags
79
+ plaiful events script export y1-s2-m1-the-object-ev-the-recovery --vo --out recovery-vo.csv # the voice-over sheet
80
+ plaiful agents # your product's SmartBuilder agents in dev (agents show <name>: one agent's config)
81
+ plaiful agents deploy # deploy or redeploy every config in resources/agents/roadforge/ (or name the files)
82
+ plaiful agents run crew-portrait role=medic # make one record (placeholder values as key=value)
83
+ plaiful agents batch crew-portrait --count 20 # start a batch (or a batch body file) → a job id
84
+ plaiful agents status crew-portrait <jobId> # a batch's progress
85
+ plaiful records import crew-portrait # dry run: records you wrote (resources/records/roadforge/crew-portrait.json)
86
+ # into the agent's table; --apply writes them, --no-render skips the art
87
+ plaiful lists # the product's SSM lists
88
+ plaiful lists set shop_type tavern blacksmith healer # write one (lists get shop_type reads it)
89
+ plaiful midas pricing # what each quest pays, in your reward kinds (MIDAS); delivered in the quest's rewards
90
+ plaiful midas pricing set scrap --base 20 --per-effort 10 # price a kind (unset <kind>, weight <step> <n>, apply [file])
91
+ plaiful upload ovid-map-biomes-tiles.json ovid-map-kingdoms-tiles.json ovid-map-colors.json # map tiles → map-data/
92
+ plaiful whoami # who you are (or which key), and your products
93
+ plaiful logout
94
+ ```
95
+
96
+ `plaiful help` lists every command and option.
97
+
98
+ ### Notes
99
+
100
+ - `--json` on any command prints the platform's answer as JSON (for agents). Exit codes: `0` done, `1` the platform
101
+ said no (invalid, not allowed, not signed in), `2` the command itself was wrong.
102
+ - Everything works in **dev**. Staging and prod get your content through Plaiful's promotion.
103
+ - `docs pull` keeps `client-config.md` (your keys) out of git with `docs/plaiful/.gitignore`, and prints the
104
+ `git rm --cached` line if it was committed before.
105
+ - `clone` needs access to the repo on GitHub (git signed in: `gh auth login` or Git Credential Manager), and
106
+ `npm install` needs npm access to the `@plaiful` packages. It writes `.env.development` only when the repo has the
107
+ web template's `.env.development.example`.
108
+ - `lists set` writes a StringList in your product's namespace. It won't touch a key (SecureString), a setting (a plain
109
+ String), or `access/*` (who may play).
110
+ - The sign-in is kept in `~/.plaiful/credentials`, never in the repo. `PLAIFUL_API_URL` or `--api` points at another API.
111
+ - You need to be on the Plaiful allowlist, and own or be shared the product (Plaiful staff: every product).
112
+ - From a PlaifulCMS checkout instead of npm: `npm install -g <path to PlaifulCMS>/packages/plaiful-cli`. The package
113
+ is public on npmjs.com; it holds no secrets, and everything it does needs a CMS sign-in or a key.
114
+
115
+ ### Keys for agents and CI
116
+
117
+ A product's owner issues keys in the CMS: Product deployment → the product → **CLI keys**. A key is shown once; set
118
+ it as `PLAIFUL_TOKEN` in CI or the agent's environment (never in the repo) and the CLI uses it instead of a sign-in:
119
+
120
+ ```sh
121
+ PLAIFUL_TOKEN=plf_k_… plaiful seed world --apply
122
+ ```
123
+
124
+ A key acts as the owner who issued it, on that one product, in dev, for the scopes picked (`docs`, `status`, `seed`,
125
+ `ovid:publish`, `lists`, `upload`). Revoking it in the CMS stops it at once; so does its issuer losing the product. The
126
+ same screen shows the product's activity: everything the CLI and its keys did.
127
+
128
+ ### For Plaiful staff
129
+
130
+ - **Design:** `docs/system/product/PARTNER_API_AND_CLI.md`.
131
+ - **Publishing a new version:** bump `version` in `package.json`, then `npm publish` from this folder, signed in to
132
+ npm as a member of the `plaiful` org.
133
+ - **Tests:** the end-to-end tests run this CLI against the partner API handler:
134
+ `lambda/functions/partner-api/__tests__/partner-api.test.js`.
package/package.json CHANGED
@@ -1,21 +1,21 @@
1
- {
2
- "name": "@plaiful/cli",
3
- "version": "0.6.0",
4
- "description": "The Plaiful CLI: work on your Plaiful product from your game repo, with no AWS access",
5
- "bin": {
6
- "plaiful": "bin/plaiful.js"
7
- },
8
- "files": [
9
- "bin",
10
- "src",
11
- "README.md"
12
- ],
13
- "engines": {
14
- "node": ">=18"
15
- },
16
- "license": "UNLICENSED",
17
- "publishConfig": {
18
- "registry": "https://registry.npmjs.org/",
19
- "access": "public"
20
- }
21
- }
1
+ {
2
+ "name": "@plaiful/cli",
3
+ "version": "0.7.0",
4
+ "description": "The Plaiful CLI: work on your Plaiful product from your game repo, with no AWS access",
5
+ "bin": {
6
+ "plaiful": "bin/plaiful.js"
7
+ },
8
+ "files": [
9
+ "bin",
10
+ "src",
11
+ "README.md"
12
+ ],
13
+ "engines": {
14
+ "node": ">=18"
15
+ },
16
+ "license": "UNLICENSED",
17
+ "publishConfig": {
18
+ "registry": "https://registry.npmjs.org/",
19
+ "access": "public"
20
+ }
21
+ }