---
name: ys-cli
description: |
  Use this skill when the user wants to use the `ys` CLI for 野生Club / yesheng:
  login, init projects, create logs, push/sync README/images/logs, switch programs,
  list/show projects, or get program documentation URLs for AI/user analysis.
  Trigger keywords: ys, yesheng, 野生, 野生Club, CLI, push, sync, project list,
  project show, program, docs, 文档, 手册, 规则, 提交.
---

# ys-cli

`ys` is the 野生Club command line tool. Run it from the user's project workspace
— the directory that contains `yesheng.config.yaml` (this is where `ys push`
reads `README.md`, `images/`, and `logs/`):

```bash
cd <the user's project directory>
ys <command>
```

Never hard-code a machine-specific path. Use the directory the user is actually
working in. If there is no `yesheng.config.yaml` yet, run `ys init` first (see
below).

If the caller is on the Windows side and must invoke a CLI installed inside WSL,
wrap the command like this (substitute the user's real distro and path):

```bash
wsl -d <distro> -e bash -lic "cd <the user's project directory> && ys <command>"
```

Do not use the WSL wrapper when already running inside WSL/Linux.

## Defaults

Production API:

```text
https://yesheng.preview.tencent-zeabur.cn/api/v1
```

Local development API:

```bash
ys login --key <API_KEY> --api-base http://localhost:3000/api/v1
```

`ys` stores credentials in `~/.yesheng/config.json`. The local workspace stores
project metadata in `yesheng.config.yaml`.

## Common Commands

Authenticate:

```bash
ys login --key <API_KEY>
```

Initialize a project:

```bash
ys init --program <PROGRAM_ID> --slug <SLUG> --name <NAME>
```

Create the next local append-only log file:

```bash
ys log new --title "Today I tested the sensor"
```

Create a quick cloud log without a local file:

```bash
ys log "Short progress update"
```

Upload assets and sync README, config, and unsynced logs:

```bash
ys push
```

`ys push` uploads referenced local images, replaces local image paths in memory
with cloud file IDs/URLs, syncs README/config/new logs, then marks successfully
submitted local log files as `synced: true`.

## Programs

List programs:

```bash
ys program list
```

Show the current program:

```bash
ys program current
```

Switch by id:

```bash
ys program use <PROGRAM_ID>
```

Interactively select a program:

```bash
ys program select
```

## Projects

List public projects in the current program:

```bash
ys project list
```

Useful filters:

```bash
ys project list --program <PROGRAM_ID>
ys project list --all
ys project list --limit 20 --offset 20
ys project list --json
```

Show a project:

```bash
ys project show <idOrSlug>
```

Show full log content:

```bash
ys project show <idOrSlug> --logs
```

Machine-readable or export modes:

```bash
ys project show <idOrSlug> --json
ys project show <idOrSlug> --download
```

## Docs

`ys docs` returns documentation URLs only. It does not fetch or summarize the
linked documents. AI tools or users should fetch the returned URLs separately
when they need the actual content.

Current program docs:

```bash
ys docs
```

URLs only:

```bash
ys docs --url
```

Structured JSON:

```bash
ys docs --json
```

Specific program or document:

```bash
ys docs <programId>
ys docs <docId>
ys docs <programId> <docId>
```

When the user asks about program rules, submission requirements, or project
instructions, run `ys docs --url`, then fetch and analyze the relevant URLs.

## Safety Rules

- Do not edit old synced logs unless the user explicitly understands they cannot
  be pushed again as replacements. Logs are append-only.
- Add log images by using Markdown image syntax in README or an unsynced log:
  `![alt](./images/example.png)`, `![alt](../images/example.png)`, or
  `![alt](/images/example.png)`.
- Images must be 5 MB or smaller.
- If `ys push` reports an existing log sequence, create a new log with
  `ys log new`; do not reuse the same sequence.
- If a command cannot connect to the API, check whether the user is using local
  dev (`http://localhost:3000/api/v1`) or the default preview API.


## Project Quality Standards (read before helping build a project)

Before creating or improving a 野生Club project, read the bundled references so
your help pushes toward a *good* project, not just a working API call:

- `references/good-project.md` — what makes a project original, specific, and real
- `references/good-log.md` — how to write dev logs that explain *why*, not just *what*
- `references/good-readme.md` — a README anyone can understand without opening code

When a student's idea is vague ("an AI assistant", "a game"), help them make it
specific and personal first. Dev logs must be written by the student in their own
words — never generate the log for them.