npm package: @pmate/cli
Description: CLI utilities for the pMate project
Latest version: 0.21.0

# pMate CLI

A TypeScript-powered command-line tool scaffold for future pMate automation.

## Development

```bash
npm install
npm run dev -- --help
```

- `npm run dev` executes the TypeScript entry point with `ts-node`.
- `npm run build` emits compiled JavaScript into `dist/`.
- `npm start` runs the compiled CLI (`dist/index.js`).

## Usage

After running `npm run build`, you can invoke the CLI locally via:

```bash
node dist/index.js --name Alice
```

When published or linked (e.g., `npm link`), the binary will be available as `pmate`:

```bash
pmate --help
pmate --name Bob
pmate add-dns --type A --value 1.2.3.4 --rr api
pmate login
pmate login --app @pmate/chat
pmate sts
pmate oss list
pmate oss upload --file ./path/to/file --key assets/file.txt
pmate oss upload --file ./path/to/file --key upload/file.txt --bucket parrot-static
pmate pr
pmate commit
pmate commit --push
pmate pr merge
pmate linear update ENG-123 --title "Updated title"
pmate linear update ENG-123 --desc $'line1\nline2'
pmate linear create --account work --title "Issue title"
pmate linear cycle
pmate linear teams --account pcs
pmate notion view <page-id-or-url>
pmate notion create --parent <page-id-or-url> --title "Sprint Notes" --content "Initial notes"
pmate notion create --private --title "Private Notes" --file ./notes.md
pmate notion update <page-id-or-url> --file ./notes.md --append
pmate vercel projects
pmate vercel deploys --project web --last-week
```

Notes:
- `pmate pr` normalizes generated PR titles to start with `feat: `, `fix: `, or `chore: ` (exactly one space after `:`).
- `pmate commit` creates an AI-generated commit from local changes.
- `pmate commit --push` also pushes the current branch to origin.
- `pmate pr merge` uses squash merge and deletes the branch by default (`--squash --delete-branch`).
- Each app in `.pmate.yaml` must define both `app` (CLI key) and `dir` (repo-relative directory, e.g. `apps/auth`).

## Aliyun credentials config

You can set Aliyun credentials in `~/.pmate/config.yaml`:

```bash
aliyun:
  ak: your_ak
  sk: your_sk
  region: cn-hangzhou
  domain: example.com
```

## Linear access guide

### Background/背景

When multiple teams or workspaces share one machine, running Linear actions from CLI often fails due to mixed API keys and unclear team defaults. `pmate linear` solves this by supporting multi-account config, per-repo overrides, and explicit team/account flags.

The goal is to make ticket operations reproducible in scripts and local workflows: pick the correct account, resolve the target team deterministically, then run create/view/update/list commands without re-authing in browser.

### 1) Add Linear account(s)

Add one or more Linear accounts to `~/.pmate/config.yaml`:

```yaml
linear:
  teamKey: ENG
  accounts:
    - title: work
      apiKey: your_linear_api_key
      # optional default team for this account
      teamKey: ENG
    - title: personal
      apiKey: your_other_linear_api_key
```

Rules:
- `accounts[].title` must be unique.
- `accounts[].apiKey` is required.
- If multiple accounts exist and you do not pass `--account`, `pmate` asks once and caches selection in `~/.pmate/linear-selection.json`.

### 2) (Optional) Pin account/team per repository

Add repo-local defaults in `.pmate.yaml`:

```yaml
linear:
  teamKey: ENG
  account:
    title: repo-work
    apiKey: your_repo_specific_linear_api_key
```

When `linear.account` is present in `.pmate.yaml`, it is used by default for that repo.

### 3) Verify access

Use these commands to confirm credentials and team visibility:

```bash
pmate linear whoami --account work
pmate linear teams --account work
pmate linear cycle --account work --team-key ENG
```

### 4) Common workflows

```bash
# create
pmate linear create --account work --team-key ENG --title "Fix login timeout"
pmate linear create --account work --repl

# read
pmate linear view ENG-123 --account work
pmate linear comments ENG-123 --account work
pmate linear sub-issues ENG-123 --account work

# update
pmate linear update ENG-123 --account work --title "Updated title"
pmate linear update ENG-123 --account work --desc $'line1\nline2'
pmate linear comment ENG-123 --account work --body "Investigated and reproduced"

# list/filter
pmate linear user-issues "Ryan" --account work --status "In Progress"
pmate linear issues --account work --team-key ENG --cycle 82 --status "Todo" --limit 100

# create issue from current GitHub PR
pmate linear pr --account work
```

## Auth session

`pmate login` stores sessions in `~/.pmate/session.json`. The file now keeps a
multi-app session registry keyed by app id, so logging into one app no longer
overwrites another app's session. Use `--app <app-id>` to authenticate against
a specific app; the default remains `@pmate/cli`.

Notes:
- Existing single-session files are migrated automatically on first read.
- Platform commands such as `pmate sts`, `pmate agent`, and `pmate app` still
  default to the `@pmate/cli` session.

## Notion config

Add a Notion integration token to `~/.pmate/config.yaml`:

```bash
notion:
  token: your_notion_integration_token
```

## Vercel config

Add your default Vercel scope to `~/.pmate/config.yaml`:

```yaml
vercel:
  scope: pancakeswap
```

Usage:

```bash
pmate vercel projects
pmate vercel projects --scope another-team
pmate vercel deploys --project web --last-week
pmate vercel deploys --project web --scope pancakeswap
```

Notes:
- `pmate vercel` is a thin wrapper around the installed `vercel` CLI.
- v1 only supports `vercel.scope` in PMate config.
- `pmate vercel deploys` requires `--project <name>`.