toy: Creator CLI for Toy Platform

Complete creator-side operations on the Toy platform via the

toy

binary (cobra CLI, server-side OAuth login): package and publish, update, preview, query. This skill does not include a command matrix — the CLI is self-descriptive enough, and hardcoding field names will only drift from the code. The skill only carries workflows and iron rules.

When to Use

Use this skill when users mention scenarios like publishing local projects/HTML/zip to Toy, updating existing Toys, viewing their Toy list or access statistics, checking publish records, etc.

Do NOT use for:

Operation/backend operations on the Toy platform (version review, whitelist, retrieving and deleting others' Toys, overall statistics) — these are beyond the capabilities of the creator
```
toy
```
CLI.
The old script-based publishing pipeline — this skill replaces it, and all operations should go through the official
```
toy
```
binary.

Prerequisites

```
toy
```
is installed. Check with
```
command -v toy
```
; if not installed, guide the user to install it (see
```
references/installation.md
```
).
Logged in. The first run of any API command may report "Login session expired, please run
```
toy login
```
", follow Rule 4 to handle this.
```
toy
```
targets the production environment, with no environment switching option (do not expose
```
--env
```
). Global flags are subject to the actual output of
```
--help-json
```
.

Discovery Mechanism (Key)

Do NOT construct commands from memory. Before using a subcommand for the first time, run:

bash

toy --help-json

The output is structured JSON, including the full command tree, positional parameters, flags,

writes

markers, and

choices

values. For a single subtree, run

toy <cmd> --help-json

JSON Field Semantics:

Field	Purpose
`commands[].path`	Command path array, e.g., `["create"]` , `["history","clear"]`
`commands[].args`	Positional parameters `{min, max, names, variadic}`
`commands[].flags`	List of flags at this level, each with `type/default/choices/required`
`commands[].writes`	`true` indicates a business write operation (e.g., `create` / `update` )
`global_flags`	Global flags (e.g., `--json` )

Try Upgrading When Features Are Missing

If the capability the user needs is truly not found in

--help-json

(the command/flag does not exist, not a typo or misremembering), the local

toy

version may be outdated with new features not yet available. In this case, upgrade once (see

references/installation.md

for the command) and recheck

--help-json

. Upgrade failures (dev build, no distribution address configured, offline) are normal; directly inform the user "Current version does not support this" instead of getting stuck or retrying repeatedly.

Iron Rules

Execute in the following priority order:

1. Always Use

--json

for AI Calls

Whether for read or write operations, AI must add

--json

when calling

toy

. Table outputs of read commands (

mylist

stats

history

) may break due to column width/hyperlink rendering changes; Chinese success prompts of write commands are not as easy to parse as structured responses.

--json

is the only stable contract.

2. Publish/Update is a Two-Step Process: "Preview → Confirm → Submit for Review", Not One-Step

When

create

update

(with

writes:true

) includes a package, the CLI first uploads and packages it, generates a preview_url, and does not submit for review by default. Submitting for review is triggered by

--yes

, which is the real confirmation gate (no client-side risk annotation, preview serves as the gate).

Correct AI Workflow:

Run without
--yes
first (with
```
--json
```
). The CLI only returns
```
{"preview_url": "..."}
```
and does not submit.
Provide the
```
preview_url
```
to the user as-is, asking them to check it in a browser.
Initiate an explicit confirmation proactively (AskUserQuestion or equivalent clear inquiry), instead of just passively saying "Let me know when you're done viewing". Present "About to submit for review" + change summary (target Toy's
```
id
```
/
```
title
```
/
```
slug
```
, what was changed, slug remains unchanged) and ask the user to explicitly reply "Submit / Do not submit". Only add
--yes
and re-run with the same parameters after receiving a clear affirmative response. If the user does not reply, gives an ambiguous answer (e.g., "Hmm" "Okay" that does not indicate submission) or says they need to modify further, do not add
```
--yes
```
.
After successful submission,
```
--json
```
will return
```
{id, status, preview_url}
```
, provide the
```
id
```
/
```
status
```
to the user.

Rule Details:

In non-interactive scenarios (AI calls),
```
--json
```
without
```
--yes
```
= preview only, no submission; with
```
--yes
```
= submit directly. Never add
--yes
before the user has viewed the preview and explicitly confirmed. After providing the preview, proactively ask "Whether to submit for review" instead of waiting passively — weak prompts ("Let me know when you're done") may make users think the review process has already started.
Purely modifying title/cover/visibility (
```
update
```
without path) has no preview link and is submitted for review directly. In this case, also use AskUserQuestion to inform "About to submit for review: <change summary>" before adding
```
--yes
```
.
```
--visibility password
```
must be paired with
```
--access-password
```
(4-32 characters); passing only
```
--access-password
```
will be treated as the password tier. Specific values/constraints are subject to
```
choices
```
in
```
--help-json
```
.

3. Perform Content Self-Check Before Publishing with Packages

toy

only packages and uploads, does not validate package content. Toy pages run under the

/toy/<slug>/

subpath; absolute path resources, root absolute redirects, etc., will cause white screens / 404 / link errors — the package can be uploaded and may pass review, but the page will be broken when opened. (Note: In-page anchors

href="#section"

are now supported and no longer a pitfall, see §2 of

references/content-checklist.md

Before running

create

update

with a path, perform content pre-check on

<path>

according to

references/content-checklist.md

:优先 use the automated pre-check methods provided in the checklist; if unavailable, manually check high-frequency pitfalls (absolute paths, hash routing vs history routing, build artifacts vs source code, cover image, slug cannot be changed) in §1–§6 of the checklist. If there are ERRORs, inform the user first and fix them before uploading, do not force upload.

See

references/content-checklist.md

(calibrated with official FAQs) for details.

4. Re-login When Login Session Expires

When error messages contain "Login session expired" "Please run

toy login

" or the envelope

code

is a session expiration code:

bash

toy login

toy login

will use browser OAuth (automatically opens a browser,

--no-open

can disable this). Retry the original command once after login. If it still fails, stop and report to the user, do not loop. See

references/error-codes.md

for details.

5. Confirm Destructive Local Operations

history clear

will delete all local publish records (only local logs, does not affect online Toys). It has

--yes

to skip confirmation. When AI needs to execute this, it must first use AskUserQuestion to confirm, then add

--yes

. Other read-only commands (

mylist

stats

whoami

history

view) can be run directly.

Typical Workflows

Workflows only anchor command names + business steps; specific parameters / flags / values are retrieved via

--help-json

to avoid drifting from the CLI.

A. First-Time Publishing of a Local Project

Confirm login status (run
```
toy login
```
if necessary).
Content Pre-check: Perform content pre-check on
```
<path>
```
according to Rule 3 (refer to
```
references/content-checklist.md
```
), fix any ERRORs first.
Run
```
create <path>
```
(with
```
--json
```
, without
--yes
),
```
<path>
```
can be a directory / single HTML / existing zip. Optionally add
```
--title
```
/
```
--slug
```
/
```
--poster
```
/
```
--visibility
```
(if title/slug are not passed, they will be derived from the path name).
Obtain the
```
preview_url
```
, provide it to the user as-is, and ask them to check it in a browser.
Proactively initiate explicit confirmation according to Rule 2 (present the change summary, ask the user to explicitly reply "Submit"), then re-run with the same parameters +
```
--yes
```
to submit for review after receiving an affirmative response.
Parse the returned
```
id
```
/
```
status
```
and provide them to the user.

B. Update an Existing Toy

Need to know the id first: Run
```
mylist
```
(with
```
--json
```
) to list your Toys, select the target
```
id
```
.
Update with package: First perform content pre-check on
```
<path>
```
according to Rule 3, then run
```
update <id> <path>
```
(without
```
--yes
```
) → obtain
```
preview_url
```
→ proactively initiate explicit confirmation according to Rule 2 → re-run with the same parameters +
```
--yes
```
to submit after receiving an affirmative response. Keep the original slug, do not use delete-recreate to change the address (slug cannot be changed after publishing).
Only modify metadata (title/cover/visibility/password): Run
```
update <id> --title ...
```
(no preview link, submit directly), inform the user first according to Rule 2 then add
```
--yes
```
.
Modify password tier:
```
--visibility password --access-password ...
```
; to change the password for an existing password tier, only pass
```
--access-password
```
. See
```
--help-json
```
for details.

C. View My Toys and Statistics

Run
```
mylist
```
(with
```
--json
```
, can use
```
--page
```
/
```
--size
```
) to view the list and visibility.
View statistics for a single Toy with
```
stats <id>
```
, default to the last 7 days (up to yesterday, current day not settled); use
```
--days N
```
or
```
--start/--end
```
(YYYY-MM-DD, maximum 90 days) for custom intervals, see
```
--help-json
```
for details. Scripts/JSON must explicitly pass
```
id
```
(if not passed, it will enter interactive selection which will fail in AI environments).

D. Infer "New Publish vs Update" Using Publish Records

When a user provides a local path and says "Publish to Toy", they often do not clarify whether it is a first-time publish or an update. First check publish records to disambiguate, do not start with

create

Run
```
history <path>
```
(with
```
--json
```
) to check if this directory/file has been published before. Records are isolated by login account, storing snapshots of successful
```
create
```
/
```
update
```
operations (including
```
id
```
/
```
title
```
/source path, etc.).
Judgment:
- Records found (with corresponding
```
id
```
  ) → most likely an update. Verify that the
```
id
```
  still exists via
```
mylist
```
  , then follow Workflow B (
```
update <id> <path>
```
  ). First confirm with the user that they want to update this Toy instead of publishing a new one.
- No records found → may be a first-time publish, or may have been published on another machine/account/path. Do not rely solely on local records: run
```
mylist
```
  to check if there is a Toy with the same name/slug online, then confirm with the user whether to use
```
create
```
  (Workflow A) or
```
update
```
  (Workflow B).
Old
toy.yaml
is only read-only supplementary clue (legacy from the old publishing pipeline, not a file maintained by this skill). If
```
history
```
finds nothing and you want to confirm further, you can read
```
toy.yaml
```
in the directory, take the
```
id
```
/
```
slug
```
/
```
title
```
as speculative clues — but must verify that the
```
id
```
still exists under the current account via
```
mylist --json
```
, do not directly treat it as fact. It may be outdated or point to someone else's project. Do not use
```
owner_mid
```
/
```
uid
```
in it to judge the account.
```
history
```
and
```
toy.yaml
```
are only local clues (do not affect online status, may be incomplete/outdated), not sources of truth. The real online status is subject to
```
mylist
```
; if unsure, let the user choose.

To clear records, use

history clear

(destructive, add

--yes

after confirmation according to Rule 5).

Error Handling Priority

Login session expired ("Login session expired" / session expiration code) → run
```
toy login
```
, retry once, do not loop.
Business errors (envelope
```
code != 0
```
message) → directly provide the message to the user, do not re-interpret.
Non-interactive environment reports prompts like "Need to add --yes" → this indicates a preview/submit gate, follow Rule 2 to go through the preview-confirmation process, do not mindlessly add
```
--yes
```
to bypass.
Flag/parameter errors (cobra reports
```
unknown flag
```
/
```
accepts N arg(s)
```
) → re-run
```
--help-json
```
to align parameter formats.
```
toy
```
does not have
```
--env
```
, do not construct it.

Things NOT to Do

Do not parse human-readable help text (
```
toy -h
```
is for users, AI uses
```
--help-json
```
).
Do not construct flags from memory (commands may be upgraded, verify every time);
```
toy
```
does not have
```
--env
```
, do not construct it.
Do not add
```
--yes
```
to
```
create
```
/
```
update
```
before the user has viewed the preview and explicitly confirmed; also do not wait passively for the user to speak, proactively ask "Whether to submit for review" according to Rule 2.
Do not skip content pre-check before uploading packages (absolute path/root absolute redirect pitfalls will break the page when opened); in-page anchors
```
href="#section"
```
are now supported and no longer an issue, do not treat them as pitfalls (see Section 2 of
```
references/content-checklist.md
```
).
Do not use "delete-recreate" to change the slug unless the user explicitly wants to change the address (slug cannot be changed after publishing, keep it during updates).
Do not create/write/maintain
```
toy.yaml
```
by default (this skill uses official CLI local records,
```
toy.yaml
```
is only for read-only compatibility); also do not include
```
toy.yaml
```
in the uploaded package.
Do not loop retry when login session expires; do not write session tokens into any output.
Do not add
```
--yes
```
to destructive commands like
```
history clear
```
without confirmation.

toy

NPX Install

Tags

SKILL.md Content (Chinese)