Using wemol-cli

Overview

wemol-cli is the operational client for Wemol modules and flows. Use it to discover modules/flows, inspect real input schemas, submit jobs, track execution, and recover outputs.

Primary rule: - Prefer executing CLI commands and reading real output over assumptions.

This SKILL.md is now self-sufficient for normal operation. references/ and examples/ are secondary for edge cases and domain-specific patterns.

When To Use

Use when: - user asks for a biology/chemistry/AI workflow that may map to Wemol modules or flows - task requires live module params, job status, logs, outputs, downloads - session/host/lang/install behavior affects task execution

Do not use when: - task is SDK/CLI source implementation work - user only asks for static code edits unrelated to running CLI

Quick Start

When context is unknown:

wemol-cli --help
wemol-cli --version
wemol-cli host
wemol-cli lang
wemol-cli module search antibody

If authentication error appears, stop and run:

wemol-cli login

If interactive login is not possible (non-TTY), use:

wemol-cli login --username <name> --password <password>

Quick Reference

Situation	Required Action	Avoid
User asks capability but no ID	module search / flow search first	guessing module/flow by name only
Any submit intent	fetch schema (--params-json or flow get) first	building payload from natural language
Flow submit	enforce task-keyed JSON	flat JSON submit
job output missing/empty	job tasks then job download	concluding job failed immediately
Auth/session issue	login / account / host / lang checks	continuing API probes while unauthenticated
User asks “need update?”	run update workflow and conclude directly	asking user to compare versions manually

Command Routing (Default)

• Capability request, no module ID:
• wemol-cli module search <keywords...>
• Catalog browsing/filtering:
• wemol-cli module list ...
• Pipeline/workflow request:
• wemol-cli flow search <keywords...> then wemol-cli flow get <flow_id>
• Need exact module payload:
• wemol-cli module get <module_id> --params-json
• Need flow payload shape:
• wemol-cli flow get <flow_id> --params-template
• Submitted job, need progress:
• wemol-cli job status <job_id> and wemol-cli job progress <job_id>
• Need task_id:
• wemol-cli job tasks <job_id>
• Output unclear:
• wemol-cli job diagnose <job_id> then wemol-cli job download <job_id>
• Historical run, unknown job_id:
• wemol-cli job list ... or wemol-cli job search ...

Core Commands And Rules

Global Options

wemol-cli --host <url> ...
wemol-cli --session-id <session_id> ...
wemol-cli --user-agent <ua> ...
wemol-cli --timeout <sec> ...
wemol-cli --secure ...
wemol-cli --verbose ...
wemol-cli --doc

Environment equivalents: - WEMOL_HOST - WEMOL_SESSION_ID - WEMOL_USER_AGENT

Rules: - Prefer persisted host --set and cached login for routine work. - Use --host / --session-id for one-off overrides. - Use --user-agent only when explicit routing/debugging requires it. - --doc exists on root and command groups (module, flow, job, host, lang, account); some leaf commands also support it depending on version.

Host / Language / Session / Account

wemol-cli host
wemol-cli host --set https://wemol.wecomput.com
wemol-cli lang
wemol-cli lang --set en
wemol-cli lang --set cn
wemol-cli account
wemol-cli logout

Rules: - module get and module get --params-json follow current language. - use account to confirm active identity and resource summary. - use logout to clear current host session before relogin/switch account.

Module Discovery And Inspection

wemol-cli module search antibody numbering
wemol-cli module list --name antibody --tag Biologics --tag Antibody --limit 20 --offset 0
wemol-cli module list --sort updated_at --desc true
wemol-cli module get <module_id>
wemol-cli module get <module_id> --params-json
wemol-cli module get <module_id> --params-json --method "<method_name>"

Rules: - module list and module search currently return enabled modules. - module list --tag is repeatable and uses AND semantics. - module search includes tag matching. - Before submit, always read --params-json; do not guess keys/types/options.

Flow Discovery And Inspection

wemol-cli flow search antibody pipeline
wemol-cli flow list --name antibody --tag Featured --tag Humanization --limit 20 --offset 0
wemol-cli flow list --sort updated_at --desc true
wemol-cli flow get <flow_id>
wemol-cli flow get <flow_id> --params-template

Rules: - flow list --tag is repeatable and uses AND semantics. - flow search includes tag matching. - flow get is source of truth for task names and nested input keys. - use --params-template whenever payload structure is uncertain.

Job Submit

Module submit:

wemol-cli job submit --module-id <module_id> --method "<method_name>" --params '{"Input":"value"}'
wemol-cli job submit --module-name "<module_name>" --params-file params.json
cat params.json | wemol-cli job submit --module-id <module_id> --params @-

Flow submit:

wemol-cli job submit --flow-id <flow_id> --params-file flow-params.json
wemol-cli job submit --flow-name "<flow_name>" --params '{"Task A":{"Input":"value"}}'
cat flow-params.json | wemol-cli job submit --flow-id <flow_id> --params @-

Rules: - Select exactly one target: --module-id / --module-name / --flow-id / --flow-name. - --method is module-only; do not use with flow submit. - --params and --params-file are mutually exclusive. - job submit supports repeatable --tag; CLI auto-adds Wemol CLI source tag. - Module payload keys must match --params-json field values exactly. - Flow payload must be task-keyed JSON ({"Task Name": {"Input": value}}). - File args accept local file path; CLI uploads automatically. - For file args, check format / value_formats from --params-json before submit. - For MultipleChoice, send array even for one option (for example {"Numbering Scheme":["imgt"]}).

Job Read / Track / Diagnose

wemol-cli job list --status Done --tag "Wemol CLI" --limit 20 --offset 0
wemol-cli job search antibody numbering
wemol-cli job status <job_id>
wemol-cli job progress <job_id>
wemol-cli job get <job_id>
wemol-cli job wait <job_id>
wemol-cli job wait <job_id> --until terminal --interval 5
wemol-cli job tasks <job_id>
wemol-cli job diagnose <job_id>
wemol-cli job cancel <job_id>

Rules: - use job list for status/history filters; job search for topic/module keyword recovery. - job wait <job_id> defaults to --until done; use --until terminal to stop on Done/Abort/Cancel. - job progress is preferred when status is too coarse. - job diagnose gives focused suggestions and executable next_commands.

Logs / Output / Download

wemol-cli job logs <job_id>
wemol-cli job logs <job_id> --task-id <task_id> --stderr
wemol-cli job logs <job_id> --task-id <task_id1>,<task_id2> --stdout

wemol-cli job output <job_id> --task-id <task_id> --name output
wemol-cli job output <job_id> --task-id <task_id1>,<task_id2> --dynamic

wemol-cli job download <job_id>
wemol-cli job download <job_id> --output ./result_dir
wemol-cli job download <job_id> --retry 3 --concurrency 8
wemol-cli job download <job_id> --no-resume
wemol-cli job download --all --output ./downloads

Rules: - job output normally requires --task-id; if missing, run job tasks first. - If output key missing or empty-data style errors (DBDataNull/similar) appear, try job download before declaring failure. - download resume is enabled by default with .wemol-download-manifest.json. - --no-resume disables state reuse. - summary includes skipped artifacts and transient/permanent failures.

Hard Rules (Must Follow)

1. No guessed payload keys
2. Never infer submit keys from natural language.

3. Always derive from module get --params-json or flow get.

4. No flow flat JSON submit

5. Flow submit must be task-keyed.

6. If user gives flat JSON, fix structure first, then ask missing values.

7. No blind retry

8. On validation error, re-read schema and payload shape first.

9. On JobModuleTaskMaxNumLimit, treat as capacity/quota issue, not payload formatting.

10. No premature failure conclusion

11. job output failure is not equal to job failure.

12. Try job tasks + job download.

13. No auth-ignore probing

14. After auth-required error, login/session handling comes first.

15. No update-question deflection

16. For “需要更新吗 / latest?” do comparison work yourself, do not tell user to compare.

Detection Triggers (Auto-Branch)

When these signals appear, branch automatically: - Authentication required / DBUserNoLogin / session null: - branch to session handling (login, account, host, lang) before further task commands. - user message contains flow_id / --flow-id / flow submit / pipeline submit: - branch to flow-shape validation (flow get, optional --params-template) before accepting payload. - output errors contain Output '<name>' was not found or empty-data style (DBDataNull, DBDataNotFound): - branch to artifact recovery (job download) before failure conclusion. - submit error contains JobModuleTaskMaxNumLimit: - branch to capacity/quota diagnosis, not payload rewrite. - user asks 需要更新吗 / latest / should I update: - branch to version/update decision workflow.

Version / Update Decision Workflow

When user asks whether update is needed:

1. Check installed version:

wemol-cli --version

1. Compare against known baseline:
2. this skill baseline is v1.0.0 (minimum)

3. if operating in this repo, also read repo CLI version from crates/cli/Cargo.toml

4. Decision:

5. installed < v1.0.0 -> update required
6. installed < repo version -> update required

7. installed == repo version (or >= v1.0.0 and no higher trusted source available) -> no mandatory update from local evidence

8. Upstream check:

9. if channel access is available, check official release channel directly
10. if blocked, report explicit blocker and what was checked

Allowed final statements: - update required - no update required from current evidence - cannot verify upstream latest due to <specific blocker>

Response Contract

When answering operational questions, include: - what was checked (exact command(s)) - observed key evidence (version/status/error marker) - decision/result category (for example update required / no update required / blocked) - next concrete command when action is needed

Do not return generic uncertainty without evidence.

When To Read References (Secondary)

Use references for extra depth, not for basic operation: - references/install.md: installer, PATH/security, cross-platform details - references/session-and-host.md: auth/session/host/lang/account nuances - references/module-workflow.md: deeper module filtering/schema patterns - references/flow-workflow.md: flow payload troubleshooting patterns - references/job-workflow.md: advanced diagnose/download behavior - references/output-and-agent-notes.md: output ambiguity interpretation

Example Triggers

Use examples when task matches known pattern: - antibody numbering: examples/antibody-numbering-variable-region.md - protein descriptors: examples/protein-physicochemical-properties.md - ADMET CSV: examples/admet-ai.md - MHC-I minimal output: examples/mhc-i-binding-prediction.md - history recovery: examples/job-history-recovery.md - flow submit + download: examples/flow-submit-and-download-recovery.md - run-limit error: examples/module-run-limit-error.md

Completion Checklist

Before concluding: - Are command and payload shapes confirmed from live CLI output? - If submit happened, were keys copied from schema (not guessed)? - If output unclear, did you try job tasks/job download before declaring failure? - If asked about update, did you run the full update decision workflow and return a direct conclusion?

Self-Check Scorecard (Pass/Fail)

Run this quick scorecard before sending the final answer:

1. Evidence check (Pass/Fail)

2. Did I run or quote concrete command evidence (--version, status, error marker, etc.)?

3. Decision check (Pass/Fail)

4. Did I provide an explicit result category (for example update required / no update required / blocked with reason)?

5. Actionability check (Pass/Fail)

6. If action is needed, did I provide the exact next command?

7. Deflection check (Pass/Fail)

8. Did I avoid pushing core comparison/diagnosis work back to the user?

If any item is Fail, revise the response before sending.