cawcut-app-run
Use when handling published CawCut Apps: browse, inspect, run a named App, /cawcut-app-run, or a selected-App handoff from cawcut-workflow. NOT for new production requests (cawcut-workflow).
How do I install this agent skill?
npx skills add https://github.com/cawcut/skill --skill cawcut-app-runIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
The skill manages CawCut applications and includes features to automatically install and update its command-line tools. It also provides automated scripts to fix media processing errors. A security concern exists regarding how these scripts handle file names on Windows, which could lead to command injection if a file path contains special characters.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 2 issues
What does this agent skill do?
CawCut App Run
Entry point for anything CawCut-App related: discovery ("what can this app do", "what apps are available"), catalog browsing, and running Apps. Wraps cawcut app list, cawcut app describe, and cawcut app run. New media production is routed by cawcut-workflow; this skill owns selected-App inspection, inputs and execution.
Skill files are English-only. SKILL.md and references/ must not contain Chinese or other non-English prose (including YAML description trigger phrases). Match the user's language only in live replies via reply_language.
For media inputs run cawcut asset upload once and keep the returned asset_ids; reuse them instead of uploading again. Retain IDs and returned URLs from App/Product/stage results before later processing.
Step -1 — Handoff state (check first)
If cawcut-workflow already selected an App for this goal, carry its selection,
catalog evidence, user inputs and asset IDs forward. Proceed to live describe
and input collection without repeating the picker. Fetch current catalog data
when resolving an ID or handling access changes, preserving the selected App.
If App inspection proves unsuitable, return the reason and evidence to workflow
planning; the canvas branch resumes without another catalog/picker loop.
Otherwise, continue at Step 0.
Step 0 — Bootstrap
Choose the login mode by execution environment
Choose by where commands actually run. On the user's own computer, run cawcut auth login --browser --json; the CLI opens the browser and waits for approval. In a remote environment, VM, or container without access to the user's browser, run cawcut auth login --device-auth --json and send the user authorization_url to open and approve on their own computer. Both modes support JSON; needing structured output is not a reason to choose device authorization. Agent names, non-TTY shells, and localhost URLs alone do not establish where commands run. Use the known execution context and explicit mode flags to override CLI auto-detection.
For device login, then run cawcut auth login --complete --wait --timeout 60 --json. If your tool has a short execution timeout, use single --complete --json calls instead, following next_poll_after_seconds. After device login is interrupted or returns wait_timeout, resume the saved current request rather than creating a new link. Browser login uses the legacy loopback callback; if interrupted, restart cawcut auth login --browser --json instead of using --complete. status=pending is not authentication success. Only retry the original operation after status=authenticated. Denial/expiry ends this request; do not silently create an endless sequence of authorization links. Never ask for a password, token, or a code copied back from the web page.
Run bootstrap as a silent guardrail, not as a user-facing phase.
- At most once per AI session. If any
cawcutcommand has already succeeded in this AI session, skip all bootstrap checks and continue. - Use only one explicit check command:
cawcut upgrade check --json.- Do not also run
cawcut --version,command -v cawcut, orcawcut auth status. - If
"update_available": true, runcawcut upgradeyourself via Bash (do not ask the user to type it). It refreshes CLI + skills. After it succeeds, continue this skill from Step 1 — do not stop or ask the user to re-invoke. - If
"ahead_of_registry": true, continue without upgrading. Do not ask the user to downgrade or runcawcut upgrade. - If the check fails because
cawcutis missing, ask the user to install the CLI via npm (external users — no git clone or repo./setup):
After install succeeds, continue bootstrap; auth is handled in step 4 below.npm install -g @ubnt/cawcut - For other check failures, continue and mention the warning only if a later CLI command fails.
- Do not also run
- Do not print "bootstrap checks passed" or ask "what would you like to run?" after bootstrap. Move directly to App discovery below.
- Let the first real command (
cawcut app list --schema,cawcut app describe, orcawcut app run) validate auth. If it fails with token/auth errors (includingToken expired), follow the login steps above. Use the mode appropriate to the execution environment, and retry the failed command once only afterstatus=authenticated. Run the CLI commands yourself; the user only approves in their browser. - This skill's references (
references/troubleshooting.md,references/app-inputs.md,references/intent-matching.md,references/app-presentation.md) live under the base directory printed at the top of this skill body —Readthem directly at<base_dir>/references/<file>.md. Do notfind/grepto locate them; that base directory can be a symlink that a plainfind <dir>silently fails to traverse. - Structured user-ask tool (check every session). In Claude Code, use
AskUserQuestionfor every enumerable choice. In Cursor, useAskQuestion. If either tool is in your allowed-tools list, you must use it for all enumerable decisions in this skill — app pick, duplicate-name pick, enum/default branches, media source, optional-input skip/provide, upload recovery — unless overflow forces a numbered text table for that batch only (see Interactive selection). Never default to a numbered text menu whileAskUserQuestion/AskQuestionis available and the option count fits. A user declining one such call is not grounds to stop using it for the next decision — see Interactive selection's opening rule for how to read the decline message.
Catalog freshness (mandatory)
Use live cawcut app list --schema --json output for discovery, scoring and ID
resolution. Refresh for a new production goal, explicit catalog refresh, account
change, changed target App or not-found/access errors. A same-goal handoff from
workflow may reuse its current-turn catalog evidence. During input/model/price
answers, retain the selected route; fetching IDs does not reopen the picker.
Before app run, resolve the selected App ID from current-turn catalog output
and inspect its live schema. Report lookup failures as failures, not "no match".
Step 1 — Intent triage
For explicit browse/discovery, present the catalog per
app-presentation; stop unless the user wants a run.
For a named App or a selected-App handoff, inspect it and collect its inputs.
For an unselected production goal, score the live catalog with the
matching rubric. If no App fits or the user
chooses a canvas, return to workflow planning with the result and supplied assets.
A single generation also uses the canvas fallback. Standalone generation requires
an explicit user /cawcut-generate invocation (it runs cawcut workflow quick).
App categories (image / video)
Each App in app list --json includes categories derived from publish metadata (image, video, text, audio). Use them to group and filter Apps by output type:
| Category | CLI filter | When to use |
|---|---|---|
image | --category image | sticker, photo edit, marketplace card, still creative |
video | --category video | ads, motion, animate, product video, presenter |
Discovery layout (required for bare invoke / browse):
- Image Apps — Apps with
categoriescontainingimage - Video Apps — Apps with
categoriescontainingvideo
Within each section, keep the existing Official Apps / My Apps / Shared Apps source grouping from CLI output. When the user's goal is clearly image-only or video-only, fetch with --category to reduce noise.
cawcut app list --schema # grouped by category + source
cawcut app list --schema --category image
cawcut app list --schema --category video
cawcut app list --schema --json # includes categories[] per app
Interactive selection (mandatory — tool first)
If the user just declined an AskUserQuestion / AskQuestion call: the tool result carries harness boilerplate telling you to "STOP what you are doing and wait for the user to tell you how to proceed." That sentence is attached automatically to every declined tool call by the runtime — it is not the user speaking, and it is not an instruction to stop using the tool. Read it as: stop the one specific action you were mid-way through (don't retry the identical question, don't proceed to run on unconfirmed choices) and look at what the user's actual next message says. It does not, by itself, license falling back to numbered text for the next enumerable decision — that next decision still must open with the tool, exactly as if the rejection had never happened. Only an explicit plain-text request from the user ("stop popping up menus", "just ask me in text") licenses a session-wide fallback. The STOP wording's urgency is not evidence of that request — do not let it override this rule.
Default behavior: For every enumerable choice, always call AskUserQuestion (Claude Code) or AskQuestion (Cursor) before showing a numbered text menu or asking the user to type 1, 2, or an app name. Text-only menus are fallback only.
One option is not a choice. Every call needs at least two viable options. When only one is actually feasible — one App matches and nothing else is worth offering, an enum carries a single allowed value — state that choice in prose and carry on: never fire a one-option popup, and never pad it with a placeholder alternative to make it look like a choice.
Tool names by host:
| Host | Tool name |
|---|---|
| Claude Code | AskUserQuestion |
| Cursor | AskQuestion |
Below, structured user-ask tool means whichever of these is available in the current session. Do not guess from capability alone — check your allowed-tools list.
Session checklist (before the first menu in this turn):
- Is
AskUserQuestionorAskQuestionavailable? If yes, you must use it for every row in the table below that fits in one call. - If no tool exists (CLI-only host), use numbered text in
reply_language. - If the tool exists but the candidate count exceeds one call (App-picker overflow, rule 7), use a numbered text table for that batch only; then resume
AskUserQuestion/AskQuestionfor the next small decision.
Forbidden while the tool is available: numbered text menus (1. … 2. …), "reply with the number or name", or asking the user to type app names, input keys, or enum values from memory.
| Step | Always use structured user-ask tool for |
|---|---|
| App picker | Every app from app list --schema (label = name + credits + short description; no app IDs) — see App-picker overflow (rule 7) when the candidate count exceeds what the tool can hold |
| Duplicate name | Each matching copy (label = description + source; no app IDs) |
| Enum / default text | Each allowed value + "Use default" / "Custom" when applicable |
| Media input | Photo already in chat / Paste HTTPS URL / Local file path |
| Optional input | Skip / Provide |
Structured user-ask tool rules:
- Call before waiting for a free-text reply whenever options are enumerable.
- One decision per form when possible (e.g.
pick-app, thenscene-photo-source). - Option
labelis what the user reads; keepidshort and stable (photo-sticker,3d-model-zh,3d-model-en). - Do not put app IDs in labels. After the user picks, run a fresh
cawcut app list --jsonin this turn, then resolve ID from that output only. - If the user picks Custom / Local file path / Paste URL, then ask one follow-up for that content (text or path) — still do not ask them to type input KEY names.
- Fallback only: Use numbered text menus in
reply_languageonly whenAskUserQuestion/AskQuestionis unavailable, or when option count/structure exceeds what the tool supports for that batch. Falling back for one decision does not exempt the next small decision — re-check and use the tool again when it fits. UX rule 11's combined text block is fallback shape only — not the default when the tool is present. - App-picker overflow: the tool typically caps at ~2–4 options per question (and ~4 questions per call). When the candidate list from
app list --schemaexceeds that, present the batch as a numbered text table for browsing — a leading#index column, then name, source, credits, description — and tell the user they can reply with either the number or the app name. This text fallback covers only that oversized batch. Once the user narrows to a specific App, every later small-option-count decision (duplicate-copy pick, enum values, media source, optional-input skip/provide) must go throughAskUserQuestion/AskQuestionagain — same pattern as the model-list menu incawcut-generate.
UX Rules
- Choice-first — when browsing without an already selected App, start with
cawcut app list --schema, then always callAskUserQuestion/AskQuestionfor app selection when the candidate count fits (numbered text only for App-picker overflow, rule 7). Do not show app IDs — use name, source, credits, description, and input summary only. - Template first — apply Step 1 (Intent triage): score the live catalog per
references/intent-matching.mdand recommend a strong match first. Return to workflow planning when no App fits or the user chooses a canvas (Step 1). - Disclose app on selection (required) — whenever an App is chosen — user pick, auto-match from a natural-language request, or your single recommendation — before asking for inputs:
- Run
cawcut app describe "<app name>"(disambiguate first if needed). - Present the App metadata table + inputs table (see "Present app inputs to users") in
reply_language. - Lead with the App name and description in prose — never say only "this app" without naming it.
- Then show the input collection menu (UX rules 11–12). Forbidden: vague lines like "this app can help you…" with no name, source, function, or input summary; jumping straight to "please provide the video path" without explaining which App and what it needs.
- Run
- Natural-language requests are allowed — translate the user's goal into an App recommendation using the Step 1 scoring rubric (
references/intent-matching.md) against app name, description, source, credits, and exposed input requirements. When one App scores ≥ 70, treat it as selected — rundescribeand disclose full app details immediately; do not wait for the user to ask "what app?". - Reply language:
- Bare skill invoke → English. If the user only runs the skill command with no substantive text (e.g.
/cawcut-app-run,cawcut-app-run, or the skill name alone), setreply_languageto English for menus, summaries, and questions. - Follow the conversation after that. Once the user adds a real request or follow-up in another language, switch
reply_languageto match that language for the rest of the session (unless they explicitly ask for English). - All prose, status summaries, option labels, questions, and recovery guidance use
reply_language. - Keep CLI commands/flags, model IDs, input keys, JSON keys, URLs, and raw error codes in English. App IDs are internal — resolve them from a fresh
cawcut app list --jsonrun in this turn when needed; never surface IDs in user-facing App lists. - Do not paste raw English CLI output as the user-facing answer; summarize it in
reply_language.
- Bare skill invoke → English. If the user only runs the skill command with no substantive text (e.g.
- Proactive discovery — for an explicit browse request or bare invocation without a selected-App handoff, immediately run
cawcut app list --schema, summarize Apps grouped by Image Apps and Video Apps (no IDs), and ask the user to choose an App or describe their goal freely. - Always inspect inputs before running — call
cawcut app describe "<app name>"first (orcawcut app describe <app_id>when resolving from--json). - Disambiguate duplicate names before run — if the name matches multiple Apps, always call
AskUserQuestion/AskQuestionwith one option per copy (description + source + input summary in labels) when the copy count fits. Wait for the click/choice before run. Numbered-text CLI fallback only when the tool is unavailable:cawcut app run "<name>" --pick <n>. - Choice-first for every fixed or enumerable value — same bar as
cawcut-generate's model and settings questions. Never ask the user to type app names, input keys, enum values, or flags from memory. Afterdescribe, if a field has a default,options, or a small known set, always callAskUserQuestion/AskQuestion(plus "use default" when applicable). Only ask for open-ended content when the schema is genuinely free text with no default and the user has not already provided it. Never default to numbered text for small enumerable decisions while the tool is available. - No unbounded input questions — forbidden patterns:
- "What app do you want to run?"
- "Please provide values for the required inputs."
- "Paste the value for
Input - Scene Photo." Instead, always show concrete numbered choices derived fromapp list --schema/app describe.
- Input collection menu before run — after
describe, collect input choices before run. Precedence: always decompose intoAskUserQuestion/AskQuestioncalls when the tool is present — one call for the "how to fill inputs" overview (defaults vs. custom) when there is more than one field, then one call per field needing a decision (media source A/B/C, text starter-vs-custom, enum value list). The combined text block below is fallback rendering only — use it only whenAskUserQuestion/AskQuestionis unavailable, or when sub-choice count exceeds what the tool can hold (App-picker overflow, Interactive selection rule 7). Do not merge decomposed decisions into a single numbered text menu while the tool is available.
Fallback example (English) — when AskUserQuestion / AskQuestion is unavailable or overflow applies:
Ready to run Photo to Sticker. Choose how to fill inputs:
1. Use defaults only (if any exist) and run — list which fields use defaults
2. Scene photo — pick one:
A. Use a photo you already shared in this chat (I'll use that file/URL)
B. Paste an HTTPS image URL
C. Give a local file path (e.g. ~/Pictures/photo.jpg, or C:\Users\you\Pictures\photo.jpg)
3. Text fields (only when required and no default) — pick a starter or write custom:
A. Use suggested prompt: "..."
B. Custom (you describe; one short message)
4. Run now with choices above
When AskUserQuestion / AskQuestion is available (required path) — same Photo to Sticker scenario, decomposed (one decision per call; labels in reply_language):
- Scene photo source —
AskUserQuestion/AskQuestionwith options:Photo already in chat— Use a photo you already shared in this chatPaste HTTPS URL— Paste an HTTPS image URLLocal file path— Give a local file path (e.g. ~/Pictures/photo.jpg, or C:\Users\you\Pictures\photo.jpg)
- Text field (if required and no default) —
AskUserQuestion/AskQuestionwith options:Use default/Use suggested prompt— show the default or suggested valueCustom— then ask one follow-up for the user's text (rule 5 above)
Adapt items to the live schema — omit decisions for inputs that do not exist. Never show input KEY names as something the user must type; keys are for CLI only.
12. Per input kind — menu, not free-form parameter entry — always present each row's choices via AskUserQuestion / AskQuestion per Interactive selection (above). The numbered menus below are text fallback shape only.
| Kind | User-facing menu (never ask for KEY names) |
|------|---------------------------------------------|
| text + default | 1) Use default (show value) 2) Custom text |
| text + no default | 1) Suggest 2–3 starters from app description 2) Custom (user writes content once) |
| text + enum/options in schema | Number every allowed option from describe --json; add "other" only if schema allows |
| image / video / audio | 1) File already in chat 2) HTTPS URL 3) Local path — user picks A/B/C, not a raw --input key |
| optional input | 1) Skip 2) Provide (then show sub-menu for that kind) |
13. Map chosen menu options to --input key=value yourself using the KEY column from describe. The user selects options, not parameter names.
14. For media inputs: pass an HTTPS URL or a local path prefixed with @ after the user picks a menu branch. Paths in this file are written POSIX-style for brevity; on Windows the same input is --input "key=@C:\Users\you\Pictures\photo.jpg", and ~ is expanded by neither the CLI nor PowerShell inside a quoted argument. Pass the path the user gave you as they gave it, quoted when it contains spaces, and never rewrite one platform's form into the other's.
15. Never use illustrative media examples as actual inputs. For image / video / audio inputs, any sample URL, path, or asset from describe output (sample:, x-cawcut-sample-url), SKILL.md, references/, or other docs is hint only — not a usable resource. Do not pass them to --input unless the user explicitly provided that exact file or URL in this conversation. If required media is missing, show the media sub-menu (rule 12) and wait — do not run with fabricated or placeholder examples; do not ask for a bare URL/path without choices.
16. Pass --wait so long jobs block until completion; relay all result URLs.
17. Always pass --download when the result is an image, video, or audio file. The CLI resolves the platform-appropriate downloads folder automatically (~/Downloads on macOS/Linux, %USERPROFILE%\Downloads on Windows) — do not hardcode a path or download the result yourself. Only skip --download if the user explicitly says they only want the URL.
18. Do not guess key names — they vary per app. Always derive from describe output (agent-side only; never expose key spelling work to the user).
19. Understand app sources before selecting an app:
Official Apps: curated apps owned by the CawCut official account.My Apps: apps owned by the authenticated user.Shared Apps: apps another user shared with the authenticated user. If the user asks for "official" or "shared", pick only from that section ofcawcut app list.
- Don't pre-inspect local media before attempting the run — do not shell out to
ls/file/sips -g pixelWidth/pixelHeight(or similar) to check a local file's size or dimensions before running. Attemptcawcut app rundirectly; if upload pre-flight fails, the CLI's error already reports the exact size/dimension and its limit — act on that error (see Errors below), not on a manual inspection you ran first.
Workflow
1. List available apps
cawcut app list --schema
# optional: --category image | --category video
Output: Apps grouped by output category (Image Apps / Video Apps), then by source (Official / My / Shared), with name, description, credits, and input schema lines when available (cawcut app list does not print app IDs in human output). Identify likely matches by app name, description, categories, source, credits, and required input kinds. Use cawcut app list --json internally when you need the app ID for automation.
Example human output shape:
Image Apps
Official Apps
Photo to Sticker 2 credits description: Turn a scene photo into a sticker
My Apps
My still template description: Custom image workflow
Video Apps
Official Apps
Product video generator 8 credits description: Generate a product ad video
Do not treat Official Apps, My Apps, and Shared Apps as interchangeable. When the same app is visible from multiple sources, prefer the source displayed by the CLI.
Translate app names/descriptions when reply_language is not English; keep input keys and source group names exact. Never show app IDs in user-facing App lists.
If the user provided a natural-language request, rank likely matches:
- Best official app/template match, when present.
- Best owned/shared app match.
- Workflow canvas fallback when no App fits or the user chooses a canvas.
Single clear match: treat as selected — run describe, then present metadata + inputs tables + input menu (UX rule 3). Do not reply with only "this app can…".
Multiple matches: show a numbered list with name, description, source, credits, and input summary for each; after the user picks, run describe and disclose full details before collecting inputs.
If the user did not provide a request, still present useful choices immediately. Do not ask an empty "what would you like to run?" question.
Present choices in reply_language. Default example (bare skill invoke / English):
Here are runnable CawCut Apps:
1. Product video generator — Generate a product ad video
Source: Official Apps; est. 8 credits; needs: prompt(text), product_image(image)
2. Generate a product ad video — My marketing template
Source: My Apps; needs: prompt(text)
3. Apply a shared style template — Shared by another user
Source: Shared Apps; needs: image(image)
You can:
A. Run 1 / 2 / 3 (I'll list required inputs next)
B. Describe your goal and I'll recommend the best App
C. Build a workflow canvas instead
If the user later writes in another language, use the same structure in reply_language.
If the user chooses an App (or a single App was auto-matched), immediately inspect it:
cawcut app describe "Product video generator"
Then present the App metadata table, inputs table, and input collection menu (UX rules 3, 11–12). Do not run until required inputs are resolved via menu choices — not free-form parameter typing.
Example — user asks to capture a video's first frame (after describe):
Found a matching App: **First/Last Frame Extractor (qa test)**
| Field | Value |
|-------|-------|
| Name | First/Last Frame Extractor (qa test) |
| Source | Official Apps |
| Cost | … credits |
| Output | First frame + last frame images |
Extracts the first and last frame from a video and outputs them as images.
| Name | Type | Required | Notes |
|------|------|----------|-------|
| … | video | yes | The video to process (MP4, WebM, etc.) |
Provide the video:
A. Use a video already shared in this chat
B. Paste an HTTPS video URL
C. Provide a local file path
2. Inspect inputs
cawcut app describe "<app name>"
Output: a table of inputs with KEY, KIND, required/optional, DEFAULT, and DESCRIPTION. Example:
App: Product video generator
Description: Generate a product ad video
Inputs — use the KEY column with --input KEY=value:
KEY KIND REQ DEFAULT DESCRIPTION
prompt text yes no Ad script or product description
requirements: Required text input.
product_image image yes no Product photo
requirements: Required image input. Provide an HTTPS URL, local file path, or {asset_id,url} object.
Run: cawcut app run "Product video generator" --input 'prompt=...' --input 'product_image=@/path/to/file'
For the raw JSON schema (includes internal app id in tool name):
cawcut app describe "<app name>" --json
Disambiguate duplicate app names (required)
When cawcut app describe or cawcut app run returns Multiple apps named "...", present a confirmation table — still no app IDs:
| # | Name | Source | Description | Credits | Inputs |
|---|
Fill rows from the CLI message (source, description, credits, input schema lines). Ask the user to pick by number or describe which copy they want. Then run:
cawcut app run "3D Model Generator" --pick 2 --input ... --wait --download --json
Only use --pick after the user confirms. If names are unique, omit --pick.
Present app inputs to users (required)
CawCut App inputs come from cawcut app describe — a KEY/KIND table plus requirement lines. Some CLIs print a ready param table from a dedicated model get-style command; CawCut does not. Render a user-facing markdown table when explaining an App; do not paste raw CLI output or vague prose.
Presentation rule: tables are for visibility; interaction is always numbered menus for enumerable/fixed values (same as cawcut-generate). Do not turn the table into "fill in each row" free input.
Use this column layout:
| Name | Type | Constraints / format | Default | Required | Notes |
|---|
Row mapping from describe / --json:
| Source | Table column |
|---|---|
KEY (properties key in JSON) | Name — exact --input key; may contain spaces — quote in shell |
x-cawcut-input-kind or KIND | Type: text / image / video / audio |
oneOf / requirements text | Constraints — HTTPS URL, @/local/path, {asset_id,url} |
x-cawcut-has-default + default | Default — none when false |
x-cawcut-required | Required — yes / no |
| DESCRIPTION + requirements | Notes — human label; x-cawcut-sample-url / sample: lines are illustrative only — never pass as --input |
App metadata table — include above the inputs table:
| Field | Value |
|---|---|
| Name | from list/describe |
| Source | Official Apps / My Apps / Shared Apps |
| Category | from categories in list JSON |
| Cost | credits from app list --schema |
| Output | image / video / audio / text (prefer categories) |
Do not include App ID in user-facing tables. Resolve ID from a fresh cawcut app list --json run in this turn when calling the CLI.
Example — Photo to Sticker:
| Field | Value |
|---|---|
| Name | Photo to Sticker |
| Source | Official Apps |
| Cost | 6.9 credits |
| Output | Sticker-style image (metallic outline + enamel border) |
| Name | Type | Constraints / format | Default | Required | Notes |
|---|---|---|---|---|---|
Input - Scene Photo | image | HTTPS URL, @/local/path (auto-upload), {asset_id,url} | none | yes | Scene/person photo → sticker effect |
User-facing menu (after table):
Scene photo for Photo to Sticker:
A. Use a photo already shared in this chat
B. Paste an HTTPS image URL
C. Provide a local file path
cawcut app run "Photo to Sticker" \
--input "Input - Scene Photo=@/path/to/photo.jpg" \
--wait --download --json
Always run describe for the live app — keys and credits vary per app and environment.
CLI flags table for cawcut app run:
| Name | Type | Constraints / options | Default | Required | Notes |
|---|---|---|---|---|---|
<app_ref> | string | App name from list, or internal ID | — | yes | quote if spaces; add --pick <n> when name is ambiguous |
--pick | number | 1-based index from disambiguation list | — | no | only when multiple Apps share the same name |
--input | key=value | KEY from describe | — | per schema | repeatable; quote keys with spaces |
--input-json | file | JSON object | — | no | mutually exclusive with --input |
--wait | flag | — | off | recommended | block until done |
--download | flag | path | omit = system Downloads | off | recommended | auto-save media results |
--json | flag | — | off | recommended | structured output |
3. Run with inputs
Pre-flight check: use this turn's live catalog to resolve the selected App ID,
then validate inputs against live describe. If the selected App is missing,
inaccessible or incompatible, report it and offer workflow canvas planning or an
App refresh. Preserve the current route during input answers; only goal/target
changes or an explicit refresh reopen matching.
Always pass --json so the CLI outputs structured JSON instead of plain text — this prevents the agent from truncating the signed result URL.
cawcut app run "Product video generator" \
--input prompt="summer sale, bright colors" \
--input product_image="https://cdn.example.com/shoe.jpg" \
--wait --download --json
Local file (auto-uploaded to CawCut assets):
cawcut app run "Product video generator" \
--input prompt="summer sale" \
--input product_image="@./shoe.jpg" \
--wait --download --json
Multiple inputs:
cawcut app run "<app name>" \
--input key1=value1 \
--input key2=value2 \
--wait --download --json
JSON file (alternative for many keys or values with special characters):
cawcut app run "<app name>" --input-json ./inputs.json --wait --download --json
inputs.json shape:
{ "prompt": "...", "product_image": "https://cdn.example.com/img.jpg" }
Do not combine --input and --input-json in one invocation.
Media upload pre-flight failures (size/dimension) — local @ paths trigger upload validation before the run proceeds. If the CLI prints a plain-text limit message (e.g. Audio file size is 22.9 MB (limit 15 MB). Re-encode or trim…) with no Code: / Category: / Suggested actions: markers, that still requires recovery — do not just echo the error. Always call AskUserQuestion / AskQuestion first with: compress/resize for the user now (sips/ffmpeg) and retry, let them fix it, or cancel. Numbered text only if the tool is unavailable. Never suggest CawCut Web. See references/troubleshooting.md for exact commands per failure type (MB limit vs longest-edge px are different fixes). Same rule in the Errors table below.
4. Download result
--download is already included in the run commands above. The CLI resolves the correct system downloads folder automatically — no path needed.
5. Deliver
The CLI outputs JSON when --json is used:
The local_path values are that platform's own: /Users/.../file.png on macOS,
C:\Users\...\Downloads\file.png on Windows. Report them back as the CLI printed them.
{
"result_url": "https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=...",
"result_urls": [
"https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=...",
"https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=..."
],
"task_id": "...",
"local_path": "/Users/.../file.png",
"local_paths": ["/Users/.../file-1.png", "/Users/.../file-2.png"],
"status": "done",
"credits_used": 12.0,
"credits_balance": 88.0
}
6. Hand off to the VN skill
After delivering the results, hand off unconditionally to cawcut-vn with every delivered local path (local_paths, or local_path when only one) and each output's cloud ref from result_assets (asset_id + exact signed url; the signed result_url when no id is known). VN import uses the cloud ref and never uploads the output again. It owns the entire VN decision — cloud import, editing flow, or no action — including whether VN is installed. Do not ask a VN menu here, do not run cawcut vn commands here, and do not re-run the App to satisfy the receiving skill's choice (decide-once).
Input kinds and formats
| KIND | --input format | Notes |
|---|---|---|
text | key=some text value | String; numbers/booleans coerced to string |
image | key=https://… or key=@/local/path.jpg | Local files are auto-uploaded; URL passed as-is |
video | key=https://… or key=@/local/path.mp4 | Same upload behaviour as image |
audio | key=https://… or key=@/local/path.mp3 | Same upload behaviour as image |
The @ prefix explicitly marks a local path for upload. Bare paths (e.g. ./file.jpg) are also auto-detected and uploaded if the file exists.
Async tasks
The CLI always prints Task: <task_id> to stdout before polling starts. Capture it — it is your recovery handle.
- With
--wait: CLI blocks, then prints all result URLs on success. - Without
--wait: CLI printsCheck status with: cawcut task status <task_id> --wait. - If
--waittimes out: CLI printsPolling timed out. Resume with: cawcut task status <task_id> --wait— run that command to resume.
Video Apps notify. A video App runs a minute or more. Before app run … --wait, say once that the user can step away and you will tell them when it lands; the CLI gives no estimate, so say "about a few minutes" (quote estimated_running_ms only if the output carries one; never the wait timeout). When the command ends done, failed or action_required, send one notification with the host's notification tool (PushNotification, one line, status:"proactive"); if its schema is deferred, load it first with ToolSearch (select:PushNotification). Skip it silently when the host has none; never raise a shell-level toast (osascript, notify-send, BurntToast). A wait timeout is not terminal: resume it, do not notify. Image Apps finish inside a turn: no notice, no notification.
Errors
If the CLI prints Code:, Category:, or Suggested actions:, present those numbered actions to the user before retrying. Use references/troubleshooting.md for fallback handling of token, app access, missing input, invalid input, credits, content policy, and timeout errors.
Many other failures are plain-text CLI messages without those markers — use the symptom→action table below (including media upload pre-flight size/dimension limits).
Extract result_urls from the JSON when present and present every URL to the user. For backward compatibility, result_url is the first URL. Also share every local_paths entry if present. Use exact signed URL values — do not truncate or strip query parameters (the ?Expires=...&Signature=...&Key-Pair-Id=... part is required for access).
Always also report credits_used (or credits_estimate if credits_used is absent) and credits_balance (or credits_balance_error) from the same JSON — every single completed run, even back-to-back ones in the same session. Never omit this because it was already shown for a prior run.
| Symptom | Action |
|---|---|
| App not found | Re-run cawcut app list; verify App name spelling |
| Multiple apps with same name | Show disambiguation table (source, description, inputs); get user confirmation; re-run with --pick <n> |
| App is not under Official Apps | Check My Apps and Shared Apps too; a user-owned or shared App is valid but should not be described as official. |
unknown input key "..." | Check cawcut app describe "<app name>"; fix key spelling |
Token expired | Follow the login steps in Step 0; retry the failed command once after status=authenticated |
| Media upload pre-flight fails (size/dimension) | Do not just print the error — always call AskUserQuestion / AskQuestion first with: compress/resize for the user now (sips/ffmpeg) and retry, let them fix it, or cancel. Numbered text only if the tool is unavailable. Never suggest CawCut Web. See references/troubleshooting.md for exact commands per failure type (MB limit vs longest-edge px are different fixes). |
| Run fails on model media limits | Inspect cawcut workflow nodes --capability <c> --model <id> --schema --json → medias[].limit. |
See references/app-inputs.md for deeper input resolution details.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/cawcut/skill/cawcut-app-run">View cawcut-app-run on skillZs</a>