@plaiful/cli 0.17.1 → 0.17.3

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 CHANGED
@@ -1,187 +1,205 @@
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
- | Animate characters: a set of sprite sheets (idle, attacks, hurt, poses, a walk sheet) per record | `plaiful animation sets`, then `plaiful animation run <set> <agent> --all` |
39
- | Make or change an art style, and its reference images | `plaiful styles save` (a dry run), then `--apply`; `plaiful styles images add <id> <images>` |
40
- | Publish your OVID declaration | `plaiful ovid check`, then `plaiful ovid publish` |
41
- | Tell HERMES your studio's strategy | `plaiful hermes strategy check`, then `plaiful hermes strategy publish` (your studio's admins) |
42
- | Run your studio's team | `plaiful studio show`, `plaiful studio invite <email> --role artist`, `plaiful studio remove <email>` (your studio's admins) |
43
- | Deploy and run worker agents | `plaiful agents deploy`, `plaiful agents run <name>` |
44
- | Choose how often each agent job runs on its own | `plaiful ooda`, then `plaiful ooda set argo --cadence 24h` |
45
-
46
- Every load starts as a dry run: it shows what would change, and changes nothing until you add `--apply`.
47
-
48
- ### Keys for coding agents and CI
49
-
50
- - A coding agent working on its own, or a CI job, can use a key instead of a sign-in.
51
- - Your product's owner makes one in the CMS: **DevOps → Deployment → your product → CLI keys**.
52
- - A key works on one product, for the jobs you pick, and stops the moment you revoke it.
53
- - Keep it out of your repo.
54
-
55
- ## Part 2: for your coding agent
56
-
57
- Every command runs as the signed-in CMS account (or a product API key that account issued), on that account's
58
- products, in **dev**.
59
-
60
- ### Commands
61
-
62
- ```sh
63
- plaiful login # opens the CMS: check the code matches, approve. 12 hours.
64
- plaiful clone my-game # clone the game repo, write .env.development, docs pull, npm install, open Zed
65
- plaiful init my-game # (a repo you already have) writes .plaiful.json (commit it; no secrets) and makes the resources/ folders
66
- plaiful docs # the platform docs, live (docs read <doc>, docs search <words>, docs changes)
67
- plaiful docs pull # your client-config.md into docs/plaiful/ (--copies: local copies of the docs too)
68
- plaiful mcp # the docs as MCP tools for your coding assistant: claude mcp add plaiful -- plaiful mcp
69
- plaiful env # rewrite .env.development from the dev client config (keeps your own lines)
70
- plaiful ovid check # checks docs/plaiful/my-game-ovid-declaration.json
71
- plaiful ovid publish # checks it again and publishes it; OVID reads it within ~5 minutes
72
- plaiful ovid show # what OVID has now
73
- plaiful seed world # dry run: what resources/world/my-game/*.json make, and what changes in dev
74
- plaiful seed world --apply # write it (then lore, then map); --reset also puts the clock, reveals and NPC bindings back
75
- plaiful seed personas # THESPIS personas and situations from resources/personas/my-game/ (same dry run / --apply)
76
- plaiful status # what OVID and THESPIS have in dev: counts per store, the clock, the declaration
77
- plaiful assets # per agent: records, and how many have art made / pending / failed / none yet
78
- plaiful assets crew-portrait --state failed # one agent's records: state, why a render failed, where the files are
79
- plaiful assets battlefield --json # also: any step that failed ({step}_step_error), and a part's source_crop and depth_min / depth_max
80
- plaiful assets regenerate battlefield --state step_failed --steps depth # re-run a step (or, without --steps, re-render: a new picture)
81
- plaiful assets regenerate building --state no_model --model # a 3D model from each record's picture (a 2d+3d Art Style; Regenerate → 3D model)
82
- plaiful quests # the quests OVID wrote: steps, and what each pays (--track, --series); quests show <id>
83
- plaiful lore # the lore sets (lore show <setId>: a set's snippets)
84
- plaiful world # the world's states and events in story order, and the clock
85
- plaiful events script write y1-s2-m1-the-object-ev-the-recovery --wait # OVID writes the event's cinematic (a draft)
86
- plaiful events script get y1-s2-m1-the-object-ev-the-recovery # the screenplay page, the versions, Soter's flags
87
- plaiful events script export y1-s2-m1-the-object-ev-the-recovery --vo --out recovery-vo.csv # the voice-over sheet
88
- plaiful events script approve y1-s2-m1-the-object-ev-the-recovery 2 # the version the game gets (--retire withdraws it)
89
- plaiful events storyboard draw y1-s2-m1-the-object-ev-the-recovery --style ink-wash --wait # a frame per shot
90
- plaiful events storyboard get y1-s2-m1-the-object-ev-the-recovery --out boards/ # the frames, saved as PNGs
91
- plaiful events edit y1-s2-m1-the-object-ev-the-recovery --title "The Recovery" # or --description, --order, --directives f.json
92
- plaiful events delete <eventId> # and quests delete <questId>; --force for official canon
93
- plaiful lore add the-sundered-wake --narrative "…" # lore reveal|hide <snippetId>, lore remove <setId>
94
- plaiful world set kessel_well false --reason "raided" # world truth|faction|var add new ones
95
- plaiful canon event <eventId> official
96
- plaiful animation sets # the animation sets you can use (sets show <id>: its states)
97
- plaiful animation sets save # save your own sets from resources/animation/my-game/*.json (sets delete <id>)
98
- plaiful animation run creature crew-portrait --all # a set on an agent's records: one sprite sheet per state
99
- plaiful styles # the art styles you can use: Plaiful's shared ones (read-only) and yours
100
- plaiful styles show style-default --out resources/styles/my-game/my-ink.json # start from one (change its id)
101
- plaiful styles save # dry run: what resources/styles/my-game/*.json would create or change (--apply saves)
102
- plaiful styles images add my-ink ref1.png ref2.jpg # reference images for one of yours (images remove <id> <key>)
103
- plaiful agents # your product's SmartBuilder agents in dev (agents show <name>: one agent's config)
104
- plaiful agents deploy # deploy or redeploy every config in resources/agents/my-game/ (or name the files)
105
- plaiful agents run crew-portrait role=medic # make one record (placeholder values as key=value)
106
- plaiful agents batch crew-portrait --count 20 # start a batch (or a batch body file) → a job id
107
- plaiful agents status crew-portrait <jobId> # a batch's progress
108
- plaiful records import crew-portrait # dry run: records you wrote (resources/records/my-game/crew-portrait.json)
109
- # into the agent's table; --apply writes them, --no-render skips the art
110
- plaiful ooda # when each agent's OODA jobs run on their own (the hourly tick)
111
- plaiful ooda set argo --cadence 24h --window 02:00-06:00 # daily, only between 02:00 and 06:00 UTC
112
- plaiful lists # the product's SSM lists
113
- plaiful lists set shop_type tavern blacksmith healer # write one (lists get shop_type reads it)
114
- plaiful midas check # check docs/plaiful/my-game-midas-declaration.json (publish: plaiful midas publish; show)
115
- plaiful midas health # MIDAS's analysis, per kind (balance: what's flagged; proposals; assess: run it now)
116
- plaiful midas wallet <uid> # a player's balances and history (wallet "platform"); midas ledger check <file>: a report's dry run
117
- plaiful midas pricing # what each quest pays, in your reward kinds (MIDAS); delivered in the quest's rewards
118
- plaiful midas pricing set scrap --base 20 --per-effort 10 # price a kind (unset <kind>, weight <step> <n>, apply [file])
119
- plaiful hermes strategy check # check docs/plaiful/hermes-strategy.json (publish: your studio's admins; no word: what HERMES has)
120
- plaiful studio list # your studios, and your role in each
121
- plaiful studio show # your studio's people and products (admins also see invites, seats and the presets)
122
- plaiful studio invite sam@example.com --role artist --products my-game # prints the invite link to send them
123
- plaiful studio invite lee@example.com --role admin # an admin: every area, every product
124
- plaiful studio invites # pending and expired invites (resend <inviteId>: a new link; cancel <inviteId>)
125
- plaiful studio set sam@example.com --role analyst --area art=edit # change someone; what you leave out stays as it is
126
- plaiful studio remove sam@example.com # asks first (--yes skips that); the product API keys they issued stop working
127
- plaiful studio audit --limit 20 # who changed what in the studio, newest first (--before <id> for older)
128
- plaiful upload ovid-map-biomes-tiles.json ovid-map-kingdoms-tiles.json ovid-map-colors.json # map tiles → map-data/
129
- plaiful whoami # who you are (or which key), and your products
130
- plaiful logout
131
- ```
132
-
133
- `plaiful help` lists every command and option.
134
-
135
- ### Notes
136
-
137
- - `--json` on any command prints the platform's answer as JSON (for agents). Exit codes: `0` done, `1` the platform
138
- said no (invalid, not allowed, not signed in), `2` the command itself was wrong.
139
- - Everything works in **dev**. Staging and prod get your content through Plaiful's promotion.
140
- - `docs pull` keeps `client-config.md` (your keys) out of git with `docs/plaiful/.gitignore`, and prints the
141
- `git rm --cached` line if it was committed before.
142
- - `clone` needs access to the repo on GitHub (git signed in: `gh auth login` or Git Credential Manager), and
143
- `npm install` needs npm access to the `@plaiful` packages. It writes `.env.development` only when the repo has the
144
- web template's `.env.development.example`.
145
- - `lists set` writes a StringList in your product's namespace. It won't touch a key (SecureString), a setting (a plain
146
- String), or `access/*` (who may play).
147
- - The sign-in is kept in `~/.plaiful/credentials`, never in the repo. `PLAIFUL_API_URL` or `--api` points at another API.
148
- - You need to be on the Plaiful allowlist, and own or be shared the product (Plaiful staff: every product).
149
- - `studio` commands act on your studio, not one product: every member can `show` it; only its admins invite, change,
150
- remove and read the `audit`. They need a sign-in (`plaiful login`), never a product key. In more than one studio,
151
- name it with `--studio <id or name>`. Roles: `admin`, or a preset (`producer`, `developer`, `narrative-designer`,
152
- `artist`, `game-designer`, `analyst`, `viewer`); `--area <area>=view|edit|manage|none` adjusts one area;
153
- `--products a,b` limits a member to some of the studio's products (default: all).
154
- - Plaiful doesn't email invites yet: `studio invite` and `studio resend` print the link, and you send it. It works
155
- for 7 days, for the invited email only.
156
- - From a PlaifulCMS checkout instead of npm: `npm install -g <path to PlaifulCMS>/packages/plaiful-cli`. The package
157
- is public on npmjs.com; it holds no secrets, and everything it does needs a CMS sign-in or a key.
158
-
159
- ### Keys for agents and CI
160
-
161
- A product's owner issues keys in the CMS: Product deployment → the product → **CLI keys**. A key is shown once; set
162
- 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:
163
-
164
- ```sh
165
- PLAIFUL_TOKEN=plf_k_… plaiful seed world --apply
166
- ```
167
-
168
- A key acts as the owner who issued it, on that one product, in dev, for the scopes picked (`docs`, `status`, `seed`,
169
- `ovid:publish`, `lists`, `upload`). Revoking it in the CMS stops it at once; so does its issuer losing the product. The
170
- same screen shows the product's activity: everything the CLI and its keys did.
171
-
172
- ### For Plaiful staff
173
-
174
- - **Design:** `docs/system/product/PARTNER_API_AND_CLI.md`.
175
- - **Publishing a new version:** bump `version` in `package.json`, then `npm publish` from this folder, signed in to
176
- npm as a member of the `plaiful` org.
177
- - **Tests:** the end-to-end tests run this CLI against the partner API handler:
178
- `lambda/functions/partner-api/__tests__/partner-api.test.js`.
179
- - **The model registry (`plaiful models`, staff only):** publish release cards with their files, push training data,
180
- and run GPU training on Google Cloud (`models train`, with your own `gcloud` sign-in). Guide:
181
- `docs/design/model-registry.md`; card format: `docs/design/model-card.md`. Tests:
182
- `lambda/functions/partner-api/__tests__/models.test.js` and `models-cli.test.js`.
183
-
184
- ## Licence
185
-
186
- Apache License 2.0: see [LICENSE](LICENSE). Versions up to 0.16.2 were published without a licence. The licence
187
- covers this CLI only, not the Plaiful name or logo, and not the Plaiful platform it talks to.
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
+ ### Keeping it up to date
29
+
30
+ You install the CLI once, on your machine. It doesn't update itself. **Update when it tells you to:**
31
+
32
+ ```sh
33
+ npm install -g @plaiful/cli@latest
34
+ ```
35
+
36
+ - **"A newer version is available":** once a day the CLI checks for a newer version, and if there is one it says so
37
+ after your command. Your command still worked. Update when you can.
38
+ - **"This needs plaiful X or later":** the platform no longer works with your version, and the command didn't run.
39
+ Update, then run it again.
40
+ - `plaiful --version` shows the version you have. Your sign-in, keys and repo settings carry over when you update.
41
+ - **CI:** install with `npm install -g @plaiful/cli@latest` in each run, so CI always has the newest. The check is off
42
+ in CI. `PLAIFUL_NO_UPDATE_CHECK=1` turns it off anywhere.
43
+ - **The MCP server** (`plaiful mcp`) keeps running the version it started with: restart your agent after updating.
44
+
45
+ ### What you'll use it for
46
+
47
+ | To | Run |
48
+ |---|---|
49
+ | Get your game's repo | `plaiful clone <product>`, or `plaiful init <product>` in a repo you already have |
50
+ | Get your product's settings | `plaiful docs pull` |
51
+ | Read the docs | `plaiful docs`, `plaiful docs search <words>` |
52
+ | Load your world into Plaiful | `plaiful seed world`, then `plaiful seed world --apply` (and `lore`, `map`, `personas`) |
53
+ | See what Plaiful has | `plaiful status`, `plaiful quests`, `plaiful lore`, `plaiful world`, `plaiful assets` |
54
+ | Get a cinematic script for a world event | `plaiful events script write <eventId> --wait`, then `plaiful events script export <eventId> --fountain` |
55
+ | Animate characters: a set of sprite sheets (idle, attacks, hurt, poses, a walk sheet) per record | `plaiful animation sets`, then `plaiful animation run <set> <agent> --all` |
56
+ | Make or change an art style, and its reference images | `plaiful styles save` (a dry run), then `--apply`; `plaiful styles images add <id> <images>` |
57
+ | Publish your OVID declaration | `plaiful ovid check`, then `plaiful ovid publish` |
58
+ | Tell HERMES your studio's strategy | `plaiful hermes strategy check`, then `plaiful hermes strategy publish` (your studio's admins) |
59
+ | Run your studio's team | `plaiful studio show`, `plaiful studio invite <email> --role artist`, `plaiful studio remove <email>` (your studio's admins) |
60
+ | Deploy and run worker agents | `plaiful agents deploy`, `plaiful agents run <name>` |
61
+ | Choose how often each agent job runs on its own | `plaiful ooda`, then `plaiful ooda set argo --cadence 24h` |
62
+
63
+ Every load starts as a dry run: it shows what would change, and changes nothing until you add `--apply`.
64
+
65
+ ### Keys for coding agents and CI
66
+
67
+ - A coding agent working on its own, or a CI job, can use a key instead of a sign-in.
68
+ - Your product's owner makes one in the CMS: **DevOps → Deployment → your product → CLI keys**.
69
+ - A key works on one product, for the jobs you pick, and stops the moment you revoke it.
70
+ - Keep it out of your repo.
71
+
72
+ ## Part 2: for your coding agent
73
+
74
+ Every command runs as the signed-in CMS account (or a product API key that account issued), on that account's
75
+ products, in **dev**.
76
+
77
+ ### Commands
78
+
79
+ ```sh
80
+ plaiful login # opens the CMS: check the code matches, approve. 12 hours.
81
+ plaiful clone my-game # clone the game repo, write .env.development, docs pull, npm install, open Zed
82
+ plaiful init my-game # (a repo you already have) writes .plaiful.json (commit it; no secrets) and makes the resources/ folders
83
+ plaiful docs # the platform docs, live (docs read <doc>, docs search <words>, docs changes)
84
+ plaiful docs pull # your client-config.md into docs/plaiful/ (--copies: local copies of the docs too)
85
+ plaiful mcp # the docs as MCP tools for your coding assistant: claude mcp add plaiful -- plaiful mcp
86
+ plaiful env # rewrite .env.development from the dev client config (keeps your own lines)
87
+ plaiful ovid check # checks docs/plaiful/my-game-ovid-declaration.json
88
+ plaiful ovid publish # checks it again and publishes it; OVID reads it within ~5 minutes
89
+ plaiful ovid show # what OVID has now
90
+ plaiful seed world # dry run: what resources/world/my-game/*.json make, and what changes in dev
91
+ plaiful seed world --apply # write it (then lore, then map); --reset also puts the clock, reveals and NPC bindings back
92
+ plaiful seed personas # THESPIS personas and situations from resources/personas/my-game/ (same dry run / --apply)
93
+ plaiful status # what OVID and THESPIS have in dev: counts per store, the clock, the declaration
94
+ plaiful assets # per agent: records, and how many have art made / pending / failed / none yet
95
+ plaiful assets crew-portrait --state failed # one agent's records: state, why a render failed, where the files are
96
+ plaiful assets battlefield --json # also: any step that failed ({step}_step_error), and a part's source_crop and depth_min / depth_max
97
+ plaiful assets regenerate battlefield --state step_failed --steps depth # re-run a step (or, without --steps, re-render: a new picture)
98
+ plaiful assets regenerate building --state no_model --model # a 3D model from each record's picture (a 2d+3d Art Style; Regenerate → 3D model)
99
+ plaiful quests # the quests OVID wrote: steps, and what each pays (--track, --series); quests show <id>
100
+ plaiful lore # the lore sets (lore show <setId>: a set's snippets)
101
+ plaiful world # the world's states and events in story order, and the clock
102
+ plaiful events script write y1-s2-m1-the-object-ev-the-recovery --wait # OVID writes the event's cinematic (a draft)
103
+ plaiful events script get y1-s2-m1-the-object-ev-the-recovery # the screenplay page, the versions, Soter's flags
104
+ plaiful events script export y1-s2-m1-the-object-ev-the-recovery --vo --out recovery-vo.csv # the voice-over sheet
105
+ plaiful events script approve y1-s2-m1-the-object-ev-the-recovery 2 # the version the game gets (--retire withdraws it)
106
+ plaiful events storyboard draw y1-s2-m1-the-object-ev-the-recovery --style ink-wash --wait # a frame per shot
107
+ plaiful events storyboard get y1-s2-m1-the-object-ev-the-recovery --out boards/ # the frames, saved as PNGs
108
+ plaiful events edit y1-s2-m1-the-object-ev-the-recovery --title "The Recovery" # or --description, --order, --directives f.json
109
+ plaiful events delete <eventId> # and quests delete <questId>; --force for official canon
110
+ plaiful lore add the-sundered-wake --narrative "…" # lore reveal|hide <snippetId>, lore remove <setId>
111
+ plaiful world set kessel_well false --reason "raided" # world truth|faction|var add new ones
112
+ plaiful canon event <eventId> official
113
+ plaiful animation sets # the animation sets you can use (sets show <id>: its states)
114
+ plaiful animation sets save # save your own sets from resources/animation/my-game/*.json (sets delete <id>)
115
+ plaiful animation run creature crew-portrait --all # a set on an agent's records: one sprite sheet per state
116
+ plaiful styles # the art styles you can use: Plaiful's shared ones (read-only) and yours
117
+ plaiful styles show style-default --out resources/styles/my-game/my-ink.json # start from one (change its id)
118
+ plaiful styles save # dry run: what resources/styles/my-game/*.json would create or change (--apply saves)
119
+ plaiful styles images add my-ink ref1.png ref2.jpg # reference images for one of yours (images remove <id> <key>)
120
+ plaiful agents # your product's SmartBuilder agents in dev (agents show <name>: one agent's config)
121
+ plaiful agents deploy # deploy or redeploy every config in resources/agents/my-game/ (or name the files)
122
+ plaiful agents run crew-portrait role=medic # make one record (placeholder values as key=value)
123
+ plaiful agents batch crew-portrait --count 20 # start a batch (or a batch body file) → a job id
124
+ plaiful agents status crew-portrait <jobId> # a batch's progress
125
+ plaiful records import crew-portrait # dry run: records you wrote (resources/records/my-game/crew-portrait.json)
126
+ # into the agent's table; --apply writes them, --no-render skips the art
127
+ plaiful ooda # when each agent's OODA jobs run on their own (the hourly tick)
128
+ plaiful ooda set argo --cadence 24h --window 02:00-06:00 # daily, only between 02:00 and 06:00 UTC
129
+ plaiful lists # the product's SSM lists
130
+ plaiful lists set shop_type tavern blacksmith healer # write one (lists get shop_type reads it)
131
+ plaiful midas check # check docs/plaiful/my-game-midas-declaration.json (publish: plaiful midas publish; show)
132
+ plaiful midas health # MIDAS's analysis, per kind (balance: what's flagged; proposals; assess: run it now)
133
+ plaiful midas wallet <uid> # a player's balances and history (wallet "platform"); midas ledger check <file>: a report's dry run
134
+ plaiful midas pricing # what each quest pays, in your reward kinds (MIDAS); delivered in the quest's rewards
135
+ plaiful midas pricing set scrap --base 20 --per-effort 10 # price a kind (unset <kind>, weight <step> <n>, apply [file])
136
+ plaiful hermes strategy check # check docs/plaiful/hermes-strategy.json (publish: your studio's admins; no word: what HERMES has)
137
+ plaiful studio list # your studios, and your role in each
138
+ plaiful studio show # your studio's people and products (admins also see invites, seats and the presets)
139
+ plaiful studio invite sam@example.com --role artist --products my-game # prints the invite link to send them
140
+ plaiful studio invite lee@example.com --role admin # an admin: every area, every product
141
+ plaiful studio invites # pending and expired invites (resend <inviteId>: a new link; cancel <inviteId>)
142
+ plaiful studio set sam@example.com --role analyst --area art=edit # change someone; what you leave out stays as it is
143
+ plaiful studio remove sam@example.com # asks first (--yes skips that); the product API keys they issued stop working
144
+ plaiful studio audit --limit 20 # who changed what in the studio, newest first (--before <id> for older)
145
+ plaiful upload ovid-map-biomes-tiles.json ovid-map-kingdoms-tiles.json ovid-map-colors.json # map tiles → map-data/
146
+ plaiful whoami # who you are (or which key), and your products
147
+ plaiful logout
148
+ ```
149
+
150
+ `plaiful help` lists every command and option.
151
+
152
+ ### Notes
153
+
154
+ - `--json` on any command prints the platform's answer as JSON (for agents). Exit codes: `0` done, `1` the platform
155
+ said no (invalid, not allowed, not signed in), `2` the command itself was wrong.
156
+ - Everything works in **dev**. Staging and prod get your content through Plaiful's promotion.
157
+ - `docs pull` keeps `client-config.md` (your keys) out of git with `docs/plaiful/.gitignore`, and prints the
158
+ `git rm --cached` line if it was committed before.
159
+ - `clone` needs access to the repo on GitHub (git signed in: `gh auth login` or Git Credential Manager), and
160
+ `npm install` needs npm access to the `@plaiful` packages. It writes `.env.development` only when the repo has the
161
+ web template's `.env.development.example`.
162
+ - `lists set` writes a StringList in your product's namespace. It won't touch a key (SecureString), a setting (a plain
163
+ String), or `access/*` (who may play).
164
+ - The sign-in is kept in `~/.plaiful/credentials`, never in the repo. `PLAIFUL_API_URL` or `--api` points at another API.
165
+ - You need to be on the Plaiful allowlist, and own or be shared the product (Plaiful staff: every product).
166
+ - `studio` commands act on your studio, not one product: every member can `show` it; only its admins invite, change,
167
+ remove and read the `audit`. They need a sign-in (`plaiful login`), never a product key. In more than one studio,
168
+ name it with `--studio <id or name>`. Roles: `admin`, or a preset (`producer`, `developer`, `narrative-designer`,
169
+ `artist`, `game-designer`, `analyst`, `viewer`); `--area <area>=view|edit|manage|none` adjusts one area;
170
+ `--products a,b` limits a member to some of the studio's products (default: all).
171
+ - Plaiful doesn't email invites yet: `studio invite` and `studio resend` print the link, and you send it. It works
172
+ for 7 days, for the invited email only.
173
+ - From a PlaifulCMS checkout instead of npm: `npm install -g <path to PlaifulCMS>/packages/plaiful-cli`. The package
174
+ is public on npmjs.com; it holds no secrets, and everything it does needs a CMS sign-in or a key.
175
+
176
+ ### Keys for agents and CI
177
+
178
+ A product's owner issues keys in the CMS: Product deployment → the product → **CLI keys**. A key is shown once; set
179
+ 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:
180
+
181
+ ```sh
182
+ PLAIFUL_TOKEN=plf_k_… plaiful seed world --apply
183
+ ```
184
+
185
+ A key acts as the owner who issued it, on that one product, in dev, up to the level picked: **read** (docs, status,
186
+ every list and show, checks and dry runs), **write** (also seed, edit, deploy and run agents, upload, save) or
187
+ **publish** (also what the game gets: `ovid publish`, `midas publish`, pricing, approving a script, official canon). Revoking it in the CMS stops it at once; so does its issuer losing the product. The
188
+ same screen shows the product's activity: everything the CLI and its keys did.
189
+
190
+ ### For Plaiful staff
191
+
192
+ - **Design:** `docs/system/product/PARTNER_API_AND_CLI.md`.
193
+ - **Publishing a new version:** bump `version` in `package.json`, then `npm publish` from this folder, signed in to
194
+ npm as a member of the `plaiful` org.
195
+ - **Tests:** the end-to-end tests run this CLI against the partner API handler:
196
+ `lambda/functions/partner-api/__tests__/partner-api.test.js`.
197
+ - **The model registry (`plaiful models`, staff only):** publish release cards with their files, push training data,
198
+ and run GPU training on Google Cloud (`models train`, with your own `gcloud` sign-in). Guide:
199
+ `docs/design/model-registry.md`; card format: `docs/design/model-card.md`. Tests:
200
+ `lambda/functions/partner-api/__tests__/models.test.js` and `models-cli.test.js`.
201
+
202
+ ## Licence
203
+
204
+ Apache License 2.0: see [LICENSE](LICENSE). Versions up to 0.16.2 were published without a licence. The licence
205
+ covers this CLI only, not the Plaiful name or logo, and not the Plaiful platform it talks to.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plaiful/cli",
3
- "version": "0.17.1",
3
+ "version": "0.17.3",
4
4
  "description": "The Plaiful CLI: work on your Plaiful product from your game repo, with no AWS access",
5
5
  "bin": {
6
6
  "plaiful": "bin/plaiful.js"
package/src/cli.js CHANGED
@@ -11,6 +11,7 @@ const fs = require('fs');
11
11
  const path = require('path');
12
12
  const { spawn, spawnSync } = require('child_process');
13
13
  const config = require('./config');
14
+ const updateCheck = require('./update-check');
14
15
  const { version } = require('../package.json');
15
16
 
16
17
  const HELP = `plaiful ${version}: work on your Plaiful product from your game repo
@@ -213,7 +214,8 @@ function makeContext(io, flags) {
213
214
  const url = config.apiUrl(flags);
214
215
  const out = (text, json) => io.stdout.write(`${flags.json ? JSON.stringify(json === undefined ? text : json, null, 2) : text}\n`);
215
216
  async function call(method, route, body, { auth = true } = {}) {
216
- const headers = { Accept: 'application/json' };
217
+ // The version lets the API turn away a CLI that's too old with "update" rather than a broken answer.
218
+ const headers = { Accept: 'application/json', 'X-Plaiful-CLI': version };
217
219
  if (body !== undefined) headers['Content-Type'] = 'application/json';
218
220
  if (auth) {
219
221
  const token = config.tokenFor(url);
@@ -276,7 +278,7 @@ async function logout(ctx) {
276
278
  async function whoami(ctx) {
277
279
  const { data } = await ctx.call('GET', '/partner/whoami');
278
280
  const lines = data.key
279
- ? [`Product API key "${data.key.name}" for ${data.key.product} (${data.key.env}), issued by ${data.email}; scopes: ${data.key.scopes.join(', ')}`]
281
+ ? [`Product API key "${data.key.name}" for ${data.key.product} (${data.key.env}), issued by ${data.email}; level: ${data.key.level}`]
280
282
  : [`${data.email}${data.staff ? ' (Plaiful staff)' : ''}, signed in until ${new Date(data.session_expires_at).toLocaleString()}`];
281
283
  for (const st of data.studios || []) lines.push(`Studio: ${st.name} (${st.role}${st.preset ? `, ${st.preset}` : ''}${st.status !== 'active' ? `, ${st.status}` : ''})`);
282
284
  lines.push(data.products.length ? 'Products:' : 'No products yet: create one in the CMS (Product deployment), or ask its owner to share it.');
@@ -1148,6 +1150,19 @@ function agentFiles(ctx, r, files) {
1148
1150
  return found;
1149
1151
  }
1150
1152
 
1153
+ /** What an agent's records get made into: its generation pathway and art style (plaiful styles show <id>). */
1154
+ function makesText(a) {
1155
+ if (((a.metadata || {}).business_purpose) === 'data') return 'records only (a data agent)';
1156
+ const g = a.generation;
1157
+ if (!g || !g.pathway) {
1158
+ const wf = ((a.system_fields || {}).workflow || {}).value;
1159
+ return wf ? `images via runpod, workflow ${wf}` : 'no image generation set (renders fall back to RunPod: set a style in SmartBuilder)';
1160
+ }
1161
+ const what = g.kind === 'image' || !g.kind ? 'images' : g.kind;
1162
+ if (g.pathway === 'runpod') return `${what} via runpod${g.runpod && g.runpod.workflow ? `, workflow ${g.runpod.workflow}` : ''}`;
1163
+ return `${what} via ${g.pathway}, ${g.style_ref ? `style ${g.style_ref}` : 'no style (the engine default)'}`;
1164
+ }
1165
+
1151
1166
  async function agents(ctx, [sub, name, ...rest]) {
1152
1167
  const r = repo(ctx);
1153
1168
  if (!sub) {
@@ -1168,6 +1183,7 @@ async function agents(ctx, [sub, name, ...rest]) {
1168
1183
  ` fields ${(a.output_fields || []).join(', ')}`,
1169
1184
  ` lists ${Object.entries(a.ssm_parameters || {}).map(([k, v]) => `${k} ← ${listSource(v)}`).join('; ') || 'none'}`,
1170
1185
  ` dedup ${a.duplicate_detection && a.duplicate_detection.enabled !== false ? `on ${[].concat(a.duplicate_detection.field || 'name').join(', ')}` : 'off'}`,
1186
+ ` makes ${makesText(a)}`,
1171
1187
  ' (--json prints the whole config)'];
1172
1188
  ctx.out(lines.join('\n'), data);
1173
1189
  return 0;
@@ -2142,6 +2158,7 @@ const COMMANDS = {
2142
2158
  function defaultIo() {
2143
2159
  return {
2144
2160
  fetch: (...a) => fetch(...a),
2161
+ latestVersion: () => updateCheck.latestVersion(),
2145
2162
  stdout: process.stdout,
2146
2163
  stderr: process.stderr,
2147
2164
  cwd: () => process.cwd(),
@@ -2184,6 +2201,15 @@ function defaultIo() {
2184
2201
  }
2185
2202
 
2186
2203
  async function main(argv, io = defaultIo()) {
2204
+ // Asked alongside the command (not `mcp`, which runs until its client closes); told after it.
2205
+ const latest = io.latestVersion && argv[0] !== 'mcp' ? io.latestVersion().catch(() => null) : null;
2206
+ const code = await run(argv, io);
2207
+ const line = latest && updateCheck.notice(version, await latest);
2208
+ if (line) io.stderr.write(`\n${line}\n`);
2209
+ return code;
2210
+ }
2211
+
2212
+ async function run(argv, io) {
2187
2213
  let flags = {};
2188
2214
  try {
2189
2215
  const parsed = parse(argv);
package/src/config.js CHANGED
@@ -69,5 +69,5 @@ function writeRepoConfig(root, config) {
69
69
 
70
70
  module.exports = {
71
71
  DEFAULT_API_URL, DEFAULT_DOCS_DIR, REPO_FILE, apiUrl, credentialsPath, readCredentials, writeCredentials,
72
- clearCredentials, tokenFor, findRepoConfig, writeRepoConfig,
72
+ clearCredentials, tokenFor, findRepoConfig, writeRepoConfig, home,
73
73
  };
@@ -0,0 +1,54 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * "A newer plaiful is available": once a day the CLI asks npm for the newest @plaiful/cli and, when it's newer than
5
+ * this one, says so on stderr after the command. It never updates by itself and never slows a command down (it runs
6
+ * alongside, capped at 1.5 s; any failure is silent). The answer is kept a day in ~/.plaiful/update-check.json.
7
+ * Off in CI (`CI` is set; CI installs @plaiful/cli@latest each run) and with PLAIFUL_NO_UPDATE_CHECK=1.
8
+ */
9
+
10
+ const fs = require('fs');
11
+ const path = require('path');
12
+ const config = require('./config');
13
+
14
+ const REGISTRY_URL = 'https://registry.npmjs.org/@plaiful/cli/latest';
15
+ const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
16
+ const TIMEOUT_MS = 1500;
17
+ const UPDATE_COMMAND = 'npm install -g @plaiful/cli@latest';
18
+
19
+ const cachePath = () => path.join(config.home(), 'update-check.json');
20
+
21
+ /** a < b, comparing major.minor.patch as numbers (a pre-release counts as its release). */
22
+ function older(a, b) {
23
+ const parts = (v) => String(v || '').replace(/^v/, '').split(/[-+]/)[0].split('.').map((n) => Number(n) || 0);
24
+ const [x, y] = [parts(a), parts(b)];
25
+ for (let i = 0; i < 3; i += 1) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) < (y[i] || 0);
26
+ return false;
27
+ }
28
+
29
+ /** The newest published version, from the day's cache or npm → a version string, or null. */
30
+ async function latestVersion({ fetch = (...a) => global.fetch(...a), now = Date.now() } = {}) {
31
+ if (process.env.CI || process.env.PLAIFUL_NO_UPDATE_CHECK) return null;
32
+ let cached = null;
33
+ try { cached = JSON.parse(fs.readFileSync(cachePath(), 'utf8')); } catch { /* none yet */ }
34
+ if (cached && cached.latest && now - Date.parse(cached.checked_at) < CHECK_EVERY_MS) return cached.latest;
35
+ try {
36
+ const res = await fetch(REGISTRY_URL, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(TIMEOUT_MS) });
37
+ if (!res.ok) return null;
38
+ const latest = (await res.json()).version;
39
+ if (!latest) return null;
40
+ try {
41
+ fs.mkdirSync(config.home(), { recursive: true });
42
+ fs.writeFileSync(cachePath(), `${JSON.stringify({ checked_at: new Date(now).toISOString(), latest })}\n`);
43
+ } catch { /* read-only home: check again next time */ }
44
+ return latest;
45
+ } catch { return null; }
46
+ }
47
+
48
+ /** The line to print when `latest` is newer than `current`, else null. */
49
+ function notice(current, latest) {
50
+ if (!latest || !older(current, latest)) return null;
51
+ return `plaiful ${latest} is available (you have ${current}). Update: ${UPDATE_COMMAND}`;
52
+ }
53
+
54
+ module.exports = { latestVersion, notice, older, UPDATE_COMMAND, REGISTRY_URL };