use-pingcode-cli

Use PingCode CLI (

pc

, REST API v2.0)

Translate the user's natural-language goal into calls to the installed

pc

command and validate the results. This skill can run in any directory: directly invoke

pc

from PATH; do not assume the CLI source code is local and do not use

cargo run

All business commands in the current CLI call the PingCode REST API v2.0, with the default base URL being

https://open.pingcode.com

and paths shaped like

/v2/pjm/workitems

. Do not use the v1

api.pingcode.com

PC_*

environment variables, or

.env

configuration methods.

Detailed credentials, v2 data structures, identifier parsing, search syntax, and error mappings are documented in

reference.md

; read it before starting.

Steps

Precheck the CLI and authentication.
- Use
```
command -v pc
```
  to confirm that it is installed. If it is not, prompt the user to follow the installation instructions in
```
reference.md
```
  (npm package
```
@pingcode/cli
```
  , Homebrew, Release binary, or cargo install), and do not continue.
- Run
```
pc doctor
```
  to validate the configuration and connectivity. It outputs structured JSON to stdout:
```
ok
```
  indicates whether all checks passed; each item in
```
checks[]
```
  has a stable
```
id
```
  and
```
status
```
  (pass/fail/warn/info/skipped); and
```
remediation.steps
```
  for failed items provides remediation steps that can be followed directly. Exit codes: 0=passed, 1=one or more checks failed, 2=the command itself encountered an error.
- When the exit code is nonzero, read the items in
```
checks[]
```
  whose
```
status=fail
```
  (such as
```
credentials_present
```
  /
```
credential_pair
```
  for missing credentials,
```
base_url_format
```
  /
```
base_url_reachable
```
  for address or network issues, or
```
token_exchange
```
  /
```
api_auth
```
  for invalid credentials), relay the corresponding
```
remediation.steps
```
  to the user, and stop so the user can resolve them. Do not repeatedly retry authentication issues.
- When the user is not logged in, ask them to run
```
pc login
```
  themselves (in automation scenarios, use
```
pc login --with-token
```
  to read the token from stdin). For enterprise credentials, use
```
pc login --method client-credentials --client-id ... --client-secret ...
```
  . Do not ask the user to paste secrets into the chat.
- For private deployments, first run
```
pc config set base-url <URL>
```
  ;
```
pc config get base-url
```
  displays the currently effective URL.
- Completion criteria:
```
pc doctor
```
  exits with code 0 (
```
ok: true
```
  ), and
```
config.base_url
```
  points to the expected environment.
Understand the intent and discover the command (do not invent parameters).
- Map the goal to a module/resource/operation (see the modules in
```
reference.md
```
  ).
- Inspect the help at each level to determine the actual subcommand and parameters:
```
pc <module> --help
```
  →
```
pc <module> <resource> --help
```
  →
```
pc <module> <resource> <operation> --help
```
  . Use the flags listed in the help and its
```
Doc:
```
  links as the source of truth;
```
Doc:
```
  now points to the v2 documentation at
```
https://developer.pingcode.com/restapi/pingcode/...
```
  .
- When more complete CLI semantics are needed, read the CLI's bundled reference:
```
pc skills read pjm
```
  ,
```
pc skills read query
```
  ,
```
pc skills read fields
```
  ,
```
pc skills read authentication
```
  , and
```
pc skills read rate-limits
```
  .
- Credential guardrails: Help output may echo credential default values. Ignore auth/token/secret-related lines when reading the help, and never repeat any secrets in your response.
- Completion criteria: the exact command to execute has been determined.
Resolve "names/identifiers" to IDs.
- When the work item identifier is known, use
  get
  directly; do not call list first. The v2
```
GET /v2/pjm/workitems/{workitem_id}
```
  endpoint supports three forms:
```
id
```
  ,
```
short_id
```
  , and
```
whole_identifier
```
  :
  - Full identifier:
    pc pjm workitem get ABC-42
  - Numeric short ID:
    pc pjm workitem get 42
  - Object ID:
    pc pjm workitem get 5e05d8448f8461dada9ba29c
    Prefer the full identifier (project prefix + number) because it is the least ambiguous. The response includes
    id
    ,
    short_id
    ,
    identifier
    (numeric), and
    whole_identifier
    (such as
    ABC-42
    ).
- Project name:
```
pc pjm project list --keywords "<name>"
```
  , and take
```
values[].id
```
  . Type name:
```
pc pjm workitem-type list-for-project --project-id <pid>
```
  , and obtain the actual
```
type_id
```
  . Person name:
```
pc organization user list --keywords "<name>"
```
  .
- List responses use the paginated structure
```
{page_index, page_size, total, values[]}
```
  .
```
page_index
```
  starts at 0, and the default page size is 30 with a maximum of 100. Paginate or increase
```
--page-size
```
  when necessary.
- When a name matches zero or multiple results, list the candidates and ask the user to confirm; do not guess.
- Completion criteria: every ID required by the command has a clear source.
Execute.
- Run read operations directly. Write/delete operations also run directly, unless the user explicitly requests a preview in this invocation (only then add
```
--dry-run
```
  ).
- Pass JSON to write operations using
```
--data
```
  : an inline string,
```
@/path/to/file
```
  , or
```
@-
```
  (stdin). When a file body is needed in another repository, write it to a temporary directory and then use
```
@/tmp/xxx.json
```
  . For v2 request body fields, follow the operation's
```
--help
```
```
Doc:
```
  page.
- When creating or updating a work item,
  type_id
  must be the actual type ID in the project. Do not treat labels such as
```
story
```
  or
```
bug
```
  as
```
type_id
```
  ; first run
```
workitem-type list-for-project
```
  .
- For PATCH requests, send only the fields being changed. Omission,
```
null
```
  , an empty string, and an empty array have different meanings; do not write the entire object back.
- All business results are pretty-printed JSON on stdout;
```
--dry-run
```
  request previews are written to stderr.
- Completion criteria: the command returns either success or an error.
Verify the output. Parse the JSON and confirm that the expected data was received: the
```
id
```
/
```
url
```
/
```
html_url
```
of a newly created object, the
```
identifier
```
/
```
whole_identifier
```
of a work item queried by identifier, the updated field values, and so on. After changing a status or property, run
```
get
```
again and compare the results. If the result does not match expectations, treat it as an issue and do not report success.
For errors, provide actionable corrections. For non-2xx responses, the CLI prints the HTTP status and the v2 error body
```
{"code":"...","message":"..."}
```
. Categorize the error according to the error mapping table in
```
reference.md
```
(authentication/permission scope, invalid ID or identifier, missing request body fields, pagination/parameters, or rate limiting), and specify the exact correction needed (which field is missing, which ID/identifier to use, or which scope is required). Retry after making the correction. Do not repeatedly retry authentication errors; hand them back to the user.
Report the results. Briefly report the outcome in Chinese: which work item was found by identifier (title/status/assignee), what was created (with
```
id
```
/
```
url
```
), what was changed, or the error and suggested correction. Do not repeat any secrets.

Do not write anything learned at runtime back to any file in this skill directory (

SKILL.md

reference.md

, etc.): the skill directory is distributed and updated with versions, so writing back will overwrite content during updates and pollute the version-controlled installation directory.

use-pingcode-cli

NPX Install

Tags

SKILL.md Content (Chinese)

Use PingCode CLI (
`pc`
, REST API v2.0)

Steps

use-pingcode-cli

NPX Install

Tags

SKILL.md Content (Chinese)

Use PingCode CLI (pc, REST API v2.0)

Steps

Use PingCode CLI (
`pc`
, REST API v2.0)