@wji.ai/cli 0.1.0

package/README.md

@@ -0,0 +1,242 @@
+# wji-cli
+
+Command line interface for the WJI AI platform (`wji-backend`).
+
+Covers auth, workspaces, the fsnode tree (ideas / datasets / files), asset
+uploads, image / video / audio generation, model discovery, agents, prompt
+presets and your profile.
+
+## Install
+
+```bash
+npm install -g @wji.ai/cli      # or: pnpm add -g @wji.ai/cli  /  yarn global add @wji.ai/cli
+wji --version
+```
+
+Requires Node 20+ (uses built-in `fetch`, `FormData` and `Blob`).
+
+From source:
+
+```bash
+git clone https://github.com/ultra-instinct-ai/wji-cli.git && cd wji-cli
+pnpm install && pnpm build
+pnpm link --global     # puts `wji` on your PATH
+```
+
+## Quick start
+
+```bash
+wji auth login --email you@example.com
+wji ws list
+wji ws use <workspaceId>            # remembered for later commands
+wji models list --feature image     # pass the MODEL column to -m
+wji gen image -m nano-banana -p "a rainy alley at dusk" --ratio 16:9 --wait
+```
+
+Against a local backend, point at the API port (the Nuxt dev server on `:3000`
+is *not* the API):
+
+```bash
+wji config set endpoint http://localhost:3002
+```
+
+## Authentication
+
+`wji auth login` stores a JWT pair in `~/.wji/config.json` (mode `0600`) and
+refreshes it automatically when the access token expires.
+
+Each refresh rotates the refresh token, and the server revokes **every**
+session if a used refresh token is presented again. Parallel `wji` processes
+therefore share one refresh through a lock file beside the config
+(`.refresh-<profile>.lock`) and re-read the config before refreshing. `wji auth
+logout` revokes the refresh token server-side; an issued access token stays
+valid until it expires.
+
+For automation, prefer a long-lived API key:
+
+```bash
+wji auth key create "ci" --save     # secret is printed once
+wji auth key list
+wji auth key revoke <id>
+```
+
+Credential precedence:
+
+```
+--token  >  $WJI_TOKEN / $WJI_API_KEY  >  profile.apiKey  >  profile.accessToken
+```
+
+`sk_…` keys are never refreshed; a JWT is.
+
+## Profiles, endpoints and orgs
+
+A profile bundles an endpoint, credentials, an org context and a default
+workspace. The default endpoint is `https://api.wji.ai`.
+
+```bash
+wji config use staging
+wji config set endpoint http://localhost:3002
+wji config profiles
+wji --profile staging ws list        # one-off override
+```
+
+Organization context is the `X-Org-Id` header, not a separate login:
+
+```bash
+wji org list
+wji org use <orgId>
+wji org personal                     # back to your personal space
+wji --no-org ws list                 # one-off personal call
+```
+
+## Commands
+
+| Group | What it does |
+| --- | --- |
+| `wji auth` | login / signup / token / whoami / refresh / logout, `auth key` for API keys |
+| `wji config` | profiles, endpoint, defaults |
+| `wji org` | organization context, members |
+| `wji ws` | workspaces, apps, members, quota, stats, templates |
+| `wji fs` | fsnode tree: ls, tree, get, mkdir, touch, set, describe, rm, sort, batch |
+| `wji dataset` | dataset nodes (character / location / prop / …) and dataset records |
+| `wji asset` | upload, import from URL, search, status, download, summary |
+| `wji canvas` | Infinite Canvas: linked canvas + selection, nodes, references, generate nodes, submit |
+| `wji gen` | `image` / `video` / `audio` generation plus `cost` estimation |
+| `wji history` | generation history: search, poll, bookmark, download |
+| `wji models` | list models and their form parameters |
+| `wji agent` | browse and manage AI agents |
+| `wji preset` | prompt presets: yours, public, workspace; fork and copy |
+| `wji skill` | agent skills: system list, push/pull SKILL.md bundles, import zip, update, rm |
+| `wji profile` | account profile, password, wallet, login history |
+
+Run `wji <group> --help` for the full option list.
+
+## Conventions
+
+- **`--json`** on any command prints the raw API response and nothing else, so
+  everything composes with `jq`.
+- **`@file` and `-`** work anywhere a long text or JSON value is expected:
+  `-p @prompt.txt`, `--content @node.json`, `-p -` to read stdin.
+- **`--set key=value`** sends arbitrary fields; dotted keys nest
+  (`--set values.quality=high`), and `true` / `false` / `null` / numbers /
+  JSON literals are parsed.
+- **References** are `assetId[:label[:weight]]`, e.g.
+  `--ref 65f0…:hero:0.6`.
+- **Destructive commands** confirm interactively; `--yes` skips, and they refuse
+  to run unconfirmed on a non-TTY.
+- Server-side filters are only offered where the API actually implements them.
+  Agent `--name` / `--category` / `--tag` are exact matches, and `wji asset
+  list` filters only by `--store`; for anything else, pipe `--json` into `jq`.
+
+## Generation
+
+Generation is asynchronous. By default `wji gen` writes a *history* entry you
+can poll:
+
+```bash
+wji gen video -m wan-3.0 -p "slow pan across the rooftop" -d 5 \
+  --start-image <assetId> --wait --timeout 1200
+
+wji history get <historyId> --wait
+wji history download <historyId> -o ./out
+```
+
+Check the price first with `wji gen cost -t video -m <model> -d 5`.
+
+Model-specific parameters come from the model's own form schema — see
+`wji models get <model>` — and are passed with `--set` or `--values`.
+
+`-m` takes the value in the `MODEL` column, which is the model's `nickname`.
+That is the unique key; plain names collide across providers.
+
+## Canvas
+
+Open a canvas in the browser and press the **link** button in its top bar. The
+open workspace, canvas and selected nodes are then available to the CLI for
+5 minutes (renewed while the tab is open), and `wji canvas` defaults to that
+canvas:
+
+```bash
+wji canvas status                                   # what is linked and selected
+wji canvas add video --from <img1> <img2> -m seedance-2.0-fast-ref -r 16:9 -d 8 \
+  -p "@image1 paddles across the lake while @image2 waits on the shore"
+wji canvas set <node> --resolution 720p --set seed=42
+wji canvas gen <node> --yes --wait                  # spends credits
+```
+
+Changes appear live in the open canvas. Pass `--canvas <id>` to work on a
+canvas that is not linked (`wji canvas list`).
+
+## Skills
+
+Skills are SKILL.md bundles (markdown only — scripts don't persist server-side).
+System skills are built-in; user skills are yours to create and attach to agents.
+
+```bash
+wji skill system                       # built-in skills (image, document, …)
+wji skill push ./my-skill              # zip a local folder (needs SKILL.md at root) and upload
+wji skill list
+wji skill pull <id> ./my-skill         # write the bundle back to disk
+wji skill cat <id>                     # print its SKILL.md
+wji skill rm <id>
+```
+
+Attach skills to an agent, and use agent version history:
+
+```bash
+wji agent skill-add <agentId> system:image user:<skillId>
+wji agent skills <agentId>
+wji agent versions <agentId>           # every edit auto-snapshots a version
+wji agent restore <agentId> <versionId>
+```
+
+Skill refs are `system:<key>` or `user:<skillId>` (a bare id is treated as `user:`).
+
+## Server limits worth knowing
+
+| Area | Limit |
+| --- | --- |
+| Generation submissions | image 30 / video 10 / audio 20 per minute, per user or key |
+| Generation queue | queued + running jobs: FREE 3 / VIP 10 / SVIP 25 → HTTP 429 |
+| Pagination | `--limit` ≤100; `-1` returns at most 500 except on opt-in endpoints |
+| Batches | `asset status` is sent 100 ids at a time; `asset summary` ≤100 ids |
+| Skills | zip ≤5MB, ≤200 files, ≤2MB per `.md`, ≤20MB total, 50 per account |
+| Creation caps | 50 workspaces, 3 organizations per account |
+| Remote import | private / internal hosts are refused, including via redirect |
+
+Rejected requests (429 / 400) are refused before any credit is charged.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | success |
+| `1` | error (validation, network, API 4xx/5xx) |
+| `77` | authentication or permission failure (401 / 403) |
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `WJI_ENDPOINT` | API base URL |
+| `WJI_TOKEN` / `WJI_API_KEY` | credential for this process |
+| `WJI_PROFILE` | profile to use |
+| `WJI_ORG_ID` | organization context |
+| `WJI_WORKSPACE` | default workspace |
+| `WJI_LOCALE` | response language (`cht`, `chs`, `en`) |
+| `WJI_CONFIG_FILE` / `WJI_CONFIG_DIR` | relocate the config |
+| `NO_COLOR` | disable colour |
+
+## Claude Code skill
+
+`skill/wji/` is an Agent Skill that teaches Claude Code to drive this CLI:
+
+The npm package ships it. After a global install:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -r "$(npm root -g)/@wji.ai/cli/skill/wji" ~/.claude/skills/wji
+```
+
+From a source checkout: `cp -r skill/wji ~/.claude/skills/wji`. Re-copy after
+upgrading the CLI so the skill matches the commands.

package/dist/commands/agent.js

@@ -0,0 +1,274 @@
+import { Command } from 'commander';
+import { WjiClient } from '../core/client.js';
+import { confirm, parseKeyValues, readValue } from '../core/prompt.js';
+import { color, detail, info, relativeTime, render, success, table, truncate } from '../core/output.js';
+/** Parse a skill ref token: `system:<key>` or `user:<id>` (bare = user id). */
+function parseSkillRef(token) {
+    const [kindRaw, rest] = token.includes(':') ? token.split(/:(.+)/) : ['user', token];
+    const kind = kindRaw === 'system' ? 'system' : 'user';
+    if (!rest)
+        throw new Error(`Invalid skill ref "${token}" — use system:<key> or user:<id>`);
+    return kind === 'system' ? { kind, key: rest } : { kind, id: rest };
+}
+function skillRefLabel(ref) {
+    if (!ref?.kind)
+        return String(ref);
+    return ref.kind === 'system' ? `system:${ref.key}` : `user:${ref.id}`;
+}
+export function agentCommand(globals) {
+    const agent = new Command('agent').description('Manage AI agents');
+    agent
+        .command('list', { isDefault: true })
+        .description('Browse the public agent marketplace')
+        .option('-n, --name <name>', 'exact agent name')
+        .option('-c, --category <name>', 'exact category')
+        .option('-t, --tag <tag>', 'agents carrying this tag')
+        .option('--include-unlisted', 'also show unlisted agents')
+        .option('--page <n>', 'page number', '1')
+        .option('--limit <n>', 'page size', '20')
+        .action(async (opts) => {
+        const client = new WjiClient(globals());
+        const result = await client.get('/ai/agent/search', {
+            name: opts.name,
+            category: opts.category,
+            tags: opts.tag,
+            includeUnlisted: opts.includeUnlisted ? 'true' : undefined,
+            page: Number(opts.page),
+            limit: Number(opts.limit),
+        });
+        render(result, (r) => printAgentTable(r));
+    });
+    agent
+        .command('mine')
+        .description('List agents you created')
+        .option('-n, --name <name>', 'exact agent name')
+        .option('-c, --category <name>', 'exact category')
+        .option('--visibility <v>', 'public | private | unlist')
+        .option('--page <n>', 'page number', '1')
+        .option('--limit <n>', 'page size', '20')
+        .action(async (opts) => {
+        const client = new WjiClient(globals());
+        const result = await client.get('/ai/agent/search/my', {
+            name: opts.name,
+            category: opts.category,
+            visibility: opts.visibility,
+            page: Number(opts.page),
+            limit: Number(opts.limit),
+        });
+        render(result, (r) => printAgentTable(r));
+    });
+    agent
+        .command('get <id>')
+        .description('Show an agent (instructions included when you own it)')
+        .action(async (id) => {
+        const client = new WjiClient(globals());
+        const a = await client.get(`/ai/agent/list/${id}`);
+        render(a, () => detail([
+            ['id', a.id],
+            ['name', a.name],
+            ['description', a.description],
+            ['model', a.model],
+            ['visibility', a.visibility],
+            ['category', a.category],
+            ['tags', (a.tags || []).join(', ')],
+            ['greeting', a.greeting],
+            ['creator', a.creator?.name || a.creator?.id || a.creator],
+            ['organization', a.organization?.id || a.organization || 'personal'],
+            ['skills', (a.skills || []).map(skillRefLabel).join(', ')],
+            ['instructions', a.instructions],
+        ]));
+    });
+    agent
+        .command('create <name>')
+        .description('Create an agent')
+        .requiredOption('-d, --description <text>', 'short description')
+        .option('-i, --instructions <text>', 'system prompt (@file / - supported)')
+        .option('-m, --model <name>', 'backing model')
+        .option('--visibility <v>', 'private | unlist | public', 'private')
+        .option('-c, --category <name>', 'category')
+        .option('-t, --tag <tag...>', 'tags')
+        .option('--greeting <text>', 'opening message')
+        .option('--skill <ref...>', 'attach skills: system:<key> or user:<skillId>')
+        .option('--set <key=value...>', 'arbitrary field')
+        .action(async (name, opts) => {
+        const client = new WjiClient(globals());
+        const created = await client.post('/ai/agent/create', {
+            name,
+            description: opts.description,
+            instructions: opts.instructions ? await readValue(opts.instructions) : undefined,
+            model: opts.model,
+            visibility: opts.visibility,
+            category: opts.category,
+            tags: opts.tag,
+            greeting: opts.greeting,
+            skills: opts.skill?.length ? opts.skill.map(parseSkillRef) : undefined,
+            ...parseKeyValues(opts.set),
+        });
+        render(created, (a) => success(`Created agent ${a.name} (${a.id})`));
+    });
+    agent
+        .command('update <id>')
+        .description('Update an agent')
+        .option('-n, --name <name>', 'new name')
+        .option('-d, --description <text>', 'new description')
+        .option('-i, --instructions <text>', 'new system prompt (@file / - supported)')
+        .option('-m, --model <name>', 'new model')
+        .option('--visibility <v>', 'private | unlist | public')
+        .option('-c, --category <name>', 'category')
+        .option('-t, --tag <tag...>', 'replace tags')
+        .option('--greeting <text>', 'opening message')
+        .option('--set <key=value...>', 'arbitrary field')
+        .action(async (id, opts) => {
+        const client = new WjiClient(globals());
+        const updated = await client.put(`/ai/agent/list/${id}`, {
+            name: opts.name,
+            description: opts.description,
+            instructions: opts.instructions ? await readValue(opts.instructions) : undefined,
+            model: opts.model,
+            visibility: opts.visibility,
+            category: opts.category,
+            tags: opts.tag,
+            greeting: opts.greeting,
+            ...parseKeyValues(opts.set),
+        });
+        render(updated, () => success(`Updated ${id}`));
+    });
+    agent
+        .command('rm <id>')
+        .description('Delete an agent')
+        .option('-y, --yes', 'skip confirmation')
+        .action(async (id, opts) => {
+        const client = new WjiClient(globals());
+        const a = await client.get(`/ai/agent/list/${id}`).catch(() => ({ name: id }));
+        if (!(await confirm(`Delete agent "${a.name}" (${id})?`, opts.yes)))
+            return info('Aborted');
+        const result = await client.delete(`/ai/agent/list/${id}`);
+        render(result, () => success(`Deleted ${id}`));
+    });
+    agent
+        .command('files <id>')
+        .description('List files attached to an agent')
+        .action(async (id) => {
+        const client = new WjiClient(globals());
+        const files = await client.get(`/ai/agent/list/${id}/files`);
+        render(files, (rows) => table(rows || [], [
+            { header: 'id', value: (f) => f.id },
+            { header: 'name', value: (f) => f.name },
+            { header: 'type', value: (f) => f.type },
+        ]));
+    });
+    agent
+        .command('categories')
+        .description('List agent categories')
+        .option('--mine', 'only categories used by your agents')
+        .action(async (opts) => {
+        const client = new WjiClient(globals());
+        const list = await client.get(opts.mine ? '/ai/agent/categories/my' : '/ai/agent/categories');
+        render(list, (rows) => rows.filter(Boolean).forEach((c) => process.stdout.write(c + '\n')));
+    });
+    agent
+        .command('tags')
+        .description('List agent tags')
+        .option('--mine', 'only tags used by your agents')
+        .action(async (opts) => {
+        const client = new WjiClient(globals());
+        const list = await client.get(opts.mine ? '/ai/agent/tags/my' : '/ai/agent/tags');
+        render(list, (rows) => rows.filter(Boolean).forEach((t) => process.stdout.write(t + '\n')));
+    });
+    agent
+        .command('recommend')
+        .description('Show recommended agents')
+        .action(async () => {
+        const client = new WjiClient(globals());
+        const rows = await client.get('/ai/agent/recommend');
+        render(rows, (list) => table(list || [], [
+            { header: 'id', value: (a) => a.id },
+            { header: 'name', value: (a) => a.name },
+            { header: 'title', value: (a) => truncate(a.recommendTitle, 40) },
+        ]));
+    });
+    agent
+        .command('skills <id>')
+        .description('Show the skills attached to an agent')
+        .action(async (id) => {
+        const client = new WjiClient(globals());
+        const a = await client.get(`/ai/agent/list/${id}`);
+        render(a.skills || [], (rows) => {
+            if (!rows.length)
+                return info(color.dim('(no skills attached)'));
+            table(rows, [
+                { header: 'kind', value: (r) => r.kind },
+                { header: 'ref', value: (r) => (r.kind === 'system' ? r.key : r.id) },
+                { header: 'name', value: (r) => r.name },
+            ]);
+        });
+    });
+    agent
+        .command('skill-add <id> <ref...>')
+        .description('Attach skills to an agent (refs: system:<key> or user:<skillId>)')
+        .action(async (id, refs) => {
+        const client = new WjiClient(globals());
+        const a = await client.get(`/ai/agent/list/${id}`);
+        const existing = (a.skills || []);
+        const seen = new Set(existing.map(skillRefLabel));
+        const added = [];
+        for (const token of refs) {
+            const ref = parseSkillRef(token);
+            if (seen.has(skillRefLabel(ref)))
+                continue;
+            existing.push(ref);
+            seen.add(skillRefLabel(ref));
+            added.push(skillRefLabel(ref));
+        }
+        const updated = await client.put(`/ai/agent/list/${id}`, { skills: existing });
+        render(updated, () => success(added.length ? `Attached ${added.join(', ')}` : 'No new skills to attach'));
+    });
+    agent
+        .command('skill-remove <id> <ref...>')
+        .description('Detach skills from an agent (refs: system:<key> or user:<skillId>)')
+        .action(async (id, refs) => {
+        const client = new WjiClient(globals());
+        const a = await client.get(`/ai/agent/list/${id}`);
+        const drop = new Set(refs.map((t) => skillRefLabel(parseSkillRef(t))));
+        const kept = (a.skills || []).filter((r) => !drop.has(skillRefLabel(r)));
+        const updated = await client.put(`/ai/agent/list/${id}`, { skills: kept });
+        render(updated, () => success(`Removed ${refs.length} skill ref(s)`));
+    });
+    agent
+        .command('versions <id>')
+        .description('List an agent\'s version history')
+        .action(async (id) => {
+        const client = new WjiClient(globals());
+        const versions = await client.get(`/ai/agent/list/${id}/versions`);
+        render(versions, (rows) => table(rows || [], [
+            { header: 'versionId', value: (v) => v.id },
+            { header: 'v', value: (v) => v.version },
+            { header: 'name', value: (v) => truncate(v.snapshot?.name, 24) },
+            { header: 'model', value: (v) => v.snapshot?.model },
+            { header: 'comment', value: (v) => truncate(v.comment, 30) },
+            { header: 'when', value: (v) => relativeTime(v.createdAt) },
+        ]));
+    });
+    agent
+        .command('restore <id> <versionId>')
+        .description('Restore an agent to a previous version')
+        .action(async (id, versionId) => {
+        const client = new WjiClient(globals());
+        const result = await client.post(`/ai/agent/list/${id}/versions/${versionId}/restore`);
+        render(result, () => success(`Restored ${id} to version ${versionId}`));
+    });
+    return agent;
+}
+function printAgentTable(result) {
+    const rows = result?.data || result || [];
+    table(rows, [
+        { header: 'id', value: (a) => a.id },
+        { header: 'name', value: (a) => truncate(a.name, 28) },
+        { header: 'model', value: (a) => a.model },
+        { header: 'visibility', value: (a) => a.visibility },
+        { header: 'category', value: (a) => a.category },
+        { header: 'updated', value: (a) => relativeTime(a.updatedAt) },
+    ]);
+    if (result?.pagination)
+        info(color.dim(`${result.pagination.total} total`));
+}