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

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

• Never infer submit keys from natural language.
• Always derive from module get --params-json or flow get.

2. No flow flat JSON submit

• Flow submit must be task-keyed.
• If user gives flat JSON, fix structure first, then ask missing values.

3. No blind retry

• On validation error, re-read schema and payload shape first.
• On JobModuleTaskMaxNumLimit, treat as capacity/quota issue, not payload formatting.

4. No premature failure conclusion

• job output failure is not equal to job failure.
• Try job tasks + job download.

5. No auth-ignore probing

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

6. No update-question deflection

• 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

2. Compare against known baseline:

• this skill baseline is v1.0.0 (minimum)
• if operating in this repo, also read repo CLI version from crates/cli/Cargo.toml

3. Decision:

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

4. Upstream check:

• if channel access is available, check official release channel directly
• 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)

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

2. Decision check (Pass/Fail)

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

3. Actionability check (Pass/Fail)

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

4. Deflection check (Pass/Fail)

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

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