WaveX CLI

Official command-line client for WaveX. After you publish @wavex/cli and install it globally, use wavex-cli to authenticate, pick workspace/project context, manage Knowledge documents and persona-driven discussions, sync AI rule guides locally, inspect work items, record Agent Runs, and import Change Briefs.

Requirements

• Node.js >=20.12.0 (see package.json engines)

Install

npm install -g @wavex/cli

Confirm the binary:

wavex-cli --help
wavex-cli --version

The published package exposes the wavex-cli executable (package.json bin). Help output may show the internal program name wavex; invoke commands with wavex-cli as above.

Upgrade

To refresh the globally installed CLI to the latest version published on npm, run:

npm install -g @wavex/cli@latest
wavex-cli --version

npm update -g can behave inconsistently across environments; prefer @latest so npm fetches the newest tarball explicitly. This CLI does not query the registry or show in-terminal update prompts during normal use—upgrade when you choose, using the command above (see also docs/cli/npm-reg-guide.md §8-1).

Configuration

• API endpoints default to the bundled WaveX CLI gateway URLs. Override if your deployment uses different hosts:
  • WAVEX_API_BASE — REST API base (JSON-RPC style routes under this base)
  • WAVEX_AUTH_BASE — browser/device login flow
• On-disk layout (typical):
  • Config and tokens: ~/.config/wavex/ (XDG_CONFIG_HOME respected)
  • Cache (rules, discuss/persona caches): ~/.cache/wavex/ (XDG_CACHE_HOME respected)

Typical workflow

1. Log in (opens a browser unless you disable it).
2. Set the active workspace, then the active project (many commands require both or derive them from config).
3. Use feature commands (knowledge, work-item, agent-run, change-brief, etc.).

wavex-cli login
wavex-cli whoami --json
wavex-cli workspace ls
wavex-cli workspace use "<workspace-uuid>"
wavex-cli project ls
wavex-cli project use "<project-uuid>"

Command reference

Global

| Command | Purpose | | --- | --- | | wavex-cli login | Device/browser login. Options: --device-name, --host (approval UI base URL), --no-browser. | | wavex-cli logout | Revoke session when possible and clear local credentials. | | wavex-cli whoami | Current profile, workspace/project IDs from config, and /account/me payload. --json is accepted; output is JSON either way. |

workspace — workspace context

| Command | Purpose | | --- | --- | | wavex-cli workspace ls | List workspaces (table or --json). | | wavex-cli workspace current | Print { workspace_id } from config. | | wavex-cli workspace use <workspaceId> | Set active workspace; clears project_id in config. |

project — project context

Requires a selected workspace (workspace use).

| Command | Purpose | | --- | --- | | wavex-cli project ls | List projects in the active workspace (--json). | | wavex-cli project current | Print { project_id } from config. | | wavex-cli project use <projectId> | Set active project. |

work-item — work items

Uses active project_id unless --project is passed. Guide/import also accept --workspace for prompt resolve context.

| Command | Purpose | | --- | --- | | wavex-cli work-item guide | Prints EXECUTION CONTRACT + bundled Work Item markdown guide. --workspace, --project, --json. | | wavex-cli work-item import-path | Prints an absolute JSON import path under ~/.wavex/work-items/ using Node APIs only (no shell date/uuidgen/mkdir; works the same on macOS/Linux/Windows). --mkdir creates the parent dir, --name <slug> picks the filename (defaults to a timestamp), --json returns { path, dir, filename, subdir }. | | wavex-cli work-item import | Bulk create from JSON array file. Required: --file. --project, --dry-run or --execute, --json. | | wavex-cli work-item ls | List items; --state, --project, --json. | | wavex-cli work-item get <id> | Fetch one item (--json). | | wavex-cli work-item create | Required: --title. Optional: --project, --description, --state, --priority, --label, --assignee, --due, --json. | | wavex-cli work-item patch <id> | Update fields (same optional flags as create, no --title required). | | wavex-cli work-item rm <id> | Delete. |

Example bulk import (no OS-specific shell commands needed for the path):

wavex-cli work-item guide --workspace "<ws_uuid>" --project "<project_uuid>"
IMPORT_FILE=$(wavex-cli work-item import-path --mkdir)
# write JSON array to $IMPORT_FILE
wavex-cli work-item import --file "$IMPORT_FILE" --project "<project_uuid>" --dry-run
wavex-cli work-item import --file "$IMPORT_FILE" --project "<project_uuid>" --execute

On Windows PowerShell: $env:IMPORT_FILE = (wavex-cli work-item import-path --mkdir), then use --file "$env:IMPORT_FILE".

knowledge — Knowledge documents

| Command | Purpose | | --- | --- | | wavex-cli knowledge ls | --scope workspace|project (default workspace). For project, pass --project or use configured project. --json. | | wavex-cli knowledge get <id> | Fetch document (--json). | | wavex-cli knowledge create | Required: --title. --scope, --project, body via --body or --body-file. | | wavex-cli knowledge patch <id> | --title, --body / --body-file. | | wavex-cli knowledge rm <id> | Delete. |

knowledge personas — Knowledge 댓글용 페르소나 목록

--knowledge 또는 --workspace. Copilot 페르소나는 항상 현재 workspace 전역 (--project 없음). --no-cache, --refresh-cache, --json 동일.

wavex-cli knowledge personas ls --knowledge "<knowledge-uuid>" --json

knowledge discuss — prepare / apply persona comment plans

| Command | Purpose | | --- | --- | | wavex-cli knowledge discuss guide <knowledgeId> | Prints the bundled LLM-oriented guide (markdown) plus quick-start lines. --workspace, optional --project, --json (wraps markdown and example commands). | | wavex-cli knowledge discuss prepare <knowledgeId> | Calls the server prepare endpoint (with local fallback when allowed). Builds discussion context, persona hints, prompt template, next_command, optional llm_cli_instructions. Writes discuss cache; supports echo/cache flags below. | | wavex-cli knowledge discuss apply <knowledgeId> | Validates or posts comments from JSON (messages[]). --dry-run (default) vs --execute, --reply-mode, stdin/--input/--input-cache, echo/cache flags. |

Prepare options (highlights)

• Context sizing: --persona-min / --persona-max, --turn-min / --turn-max, --seed, --with-existing-comments-min / --max or single --with-existing-comments, --style-mix (CSV, e.g. 평가,비평,질문,보완제안)
• --workspace override
• --echo-format: json-minify (default), json-minify-base64, gzip-base64
• --cache-mode: project-only (default), tmp-only, tmp-and-project; --cache-path overrides the cache root
• --copy copies next_command to the OS clipboard when possible
• --json prints the full decorated payload (includes echo, echo_meta, cache_paths)

Apply options

• Input: --input <file>, --input-cache <path>, or pipe JSON on stdin (non-TTY)
• --reply-mode: mixed (default), real-reply, mention
• Same --echo-format, --cache-mode, --cache-path as prepare
• --execute performs writes; omitting it keeps dry-run preview behavior

Prepare response extras (for automation / LLM)

Enhanced client-side fields include question_analysis, persona_prompt_profiles, persona_snapshot_version under discussion_context, plus llm_cli_instructions and next_command.

Apply response

JSON includes reply_link_stats (temp-id mapping, real-reply vs mention fallbacks, etc.) alongside previews or created rows.

Example end-to-end pattern (paths match knowledge discuss guide / 웹 «LLM용 CLI 지시 복사»: ~/.wavex/discuss/ + ISO 스탬프 짝):

mkdir -p ~/.wavex/discuss
wavex-cli persona ls --knowledge "<knowledge-uuid>" --json
wavex-cli knowledge discuss prepare "<knowledge-uuid>" \
  --workspace "<workspace-uuid>" \
  --persona-min 3 --persona-max 6 --turn-min 2 --turn-max 4 --seed 4242 \
  --with-existing-comments-min 80 --with-existing-comments-max 120 \
  --style-mix "평가,비평,질문,보완제안" \
  --json > ~/.wavex/discuss/knowledge-<knowledge-uuid>-prepare-<UTC_STAMP>.json
# Write plan JSON (root: messages[]) to the paired plan path with the same <UTC_STAMP>
wavex-cli knowledge discuss apply "<knowledge-uuid>" \
  --input ~/.wavex/discuss/knowledge-<knowledge-uuid>-plan-<UTC_STAMP>.json \
  --reply-mode mixed --dry-run
wavex-cli knowledge discuss apply "<knowledge-uuid>" \
  --input ~/.wavex/discuss/knowledge-<knowledge-uuid>-plan-<UTC_STAMP>.json \
  --reply-mode mixed --execute

messages[] entries should include persona_id (UUID) when possible; resolving by persona_name is supported but ambiguous names fail fast.

persona — personas and cache

| Command | Purpose | | --- | --- | | wavex-cli persona ls | List workspace-global Copilot personas: --knowledge (doc → workspace) or --workspace. --no-cache, --refresh-cache, --json. | | wavex-cli persona cache status | Cache validity for resolved workspace (--json). | | wavex-cli persona cache clear | Clear cache; --scope workspace or legacy project subtree; optional --workspace / --project. | | wavex-cli persona cache refresh <knowledgeId> | Force API refresh for knowledge’s workspace (--json). |

rules — AI / LLM rule guide cache

| Command | Purpose | | --- | --- | | wavex-cli rules pull | Downloads workspace guide markdown (project_id appended when set in config). --out <dir> sets a local directory; also writes the global cache path (printed on success). Requires active workspace. |

agent-run — Agent Run timeline

Requires workspace and project (config or flags).

| Command | Purpose | | --- | --- | | wavex-cli agent-run guide | Prints quick-start lines and the bundled Agent Run markdown guide. --workspace, --project, --json. | | wavex-cli agent-run import-path | Prints an absolute Markdown import path under ~/.wavex/agent-runs/ using Node APIs only (no shell date/uuidgen/mkdir; works the same on macOS/Linux/Windows). --mkdir creates the parent dir, --name <slug> picks the filename (defaults to a timestamp), --json returns { path, dir, filename, subdir }. | | wavex-cli agent-run ls | Lists runs: --workspace, --project, --status, --include-subruns, --limit (1–500, default 100), --json. | | wavex-cli agent-run get <run_id> | Fetch one run (--workspace, --project, --json). | | wavex-cli agent-run import --file <path> | Parse Markdown (YAML frontmatter + ## sections) and validate. Default dry-run; pass --execute to insert. --workspace, --project, --json. | | wavex-cli agent-run patch <run_id> | Partial update; many --title, --status, --agent-name, token/cost fields, --system-summary-json, --metadata-json, --context-tags, --changed-files, etc. | | wavex-cli agent-run message add <run_id> --message-file <path> | Append a timeline message; --role, --channel, --level, --source, --step-index, --pinned, --metadata-json. |

Example import (no OS-specific shell commands needed for the path):

IMPORT_FILE=$(wavex-cli agent-run import-path --mkdir)
# write Markdown to $IMPORT_FILE
wavex-cli agent-run import \
  --file "$IMPORT_FILE" \
  --workspace "<workspace-uuid>" \
  --project "<project-uuid>" \
  --dry-run
wavex-cli agent-run import \
  --file "$IMPORT_FILE" \
  --workspace "<workspace-uuid>" \
  --project "<project-uuid>" \
  --execute

change-brief — 날짜별 변경 브리프

Requires workspace and project (config or flags). guide는 기간별 운영 안내를 출력하며, import는 기본 dry-run 후 --execute로 실제 저장함.

| Command | Purpose | | --- | --- | | wavex-cli change-brief guide | Change Brief JSON 작성·적재 guide 출력. --workspace, --project, --range today|week|all, --json. | | wavex-cli change-brief ls | 날짜별 브리프 목록. --workspace, --project, --limit (1–100, default 30), --cursor-date, --json. | | wavex-cli change-brief get <brief_id> | 단일 날짜 브리프 상세 조회. --workspace, --project, --json. | | wavex-cli change-brief import --file <path> | 날짜별 JSON payload 검증·upsert. Default dry-run; pass --execute to write. |

Guide range:

• today: 기본값. 오늘 1일치 커밋을 단일 JSON으로 작성함.
• week: 최근 1주일 커밋을 날짜별 JSON으로 분리해 순차 처리함.
• all: origin/main 전체 기간을 날짜별 JSON으로 백필함.

Example import:

mkdir -p ~/.wavex/change-briefs
wavex-cli change-brief guide \
  --workspace "<workspace-uuid>" \
  --project "<project-uuid>" \
  --range today
wavex-cli change-brief import \
  --file ~/.wavex/change-briefs/change-brief-<UTC_STAMP>-daily.json \
  --workspace "<workspace-uuid>" \
  --project "<project-uuid>" \
  --dry-run
wavex-cli change-brief import \
  --file ~/.wavex/change-briefs/change-brief-<UTC_STAMP>-daily.json \
  --workspace "<workspace-uuid>" \
  --project "<project-uuid>" \
  --execute

workspace_id and project_id stay in CLI flags only; do not put them in the JSON payload. Commit IDs must be pushed Git SHAs that exist on a remote branch.

Optional LOC fields are supported in import JSON. commits[] can include lines_added, lines_deleted, lines_changed, files_changed; files[] can include lines_added, lines_deleted, lines_changed, loc_before, loc_after, churn_rate, binary; and day root can include total_lines_added, total_lines_deleted, total_lines_changed, total_files_changed, avg_lines_per_commit.

Notes

• Many subcommands print JSON by default or support --json for scripting.
• Errors and some built-in hints may appear in Korean depending on server and client strings.
• Clipboard copy (knowledge discuss prepare --copy) needs a OS clipboard helper (pbcopy, wl-copy, xclip, etc.) on Linux.