Create a Job

Purpose

Create one cloud Job from a published BioLine Flow version and JSON spec. This command submits and monitors BioLine Jobs only; statistics, plotting, tables, and reports belong to a separate downstream skill.

Syntax

fkit job create [OPTIONS] <SPEC>

SPEC format

SPEC is a local JSON file. Prefer the compact format below: fkit job create reads the selected Flow version's server template, then applies external input bindings and parameter overrides. You do not need to copy the complete task graph.

Read the actual node names, ports, and parameters first; never guess them:

fkit flow inspect <FLOW_VERSION_ID> --json
fkit job template <FLOW_VERSION_ID> --json

job template only reads data; it does not create a Job. Its tasks[].name identifies a node, and tasks[].cmdParams[] contains that node's saved parameters and defaults. This output is not a CLI spec that must be submitted unchanged. It may contain inputFiles without the top-level inputs required by the fkit CLI, so saving the template alone is not sufficient.

Field	Rule
name	Required Job name; follow the naming rules below.
flowVersionId	Required exact Flow version ID obtained from a query.
outputDir	Required output directory; follow the existing directory rules below.
inputs	Required by the fkit CLI, including "inputs": [] for a Flow without external inputs. Each binding is {"fileId": ..., "taskName": ..., "taskPortName": ...}. Bind all required inputs when the Flow has them.
params	Optional explicit overrides, each {"taskName": ..., "paramKey": ..., "paramValue": "..."}. Unlisted parameters keep their saved Flow values.

Use the actual node name for inputs[].taskName, and the node port's display name for taskPortName. Read these from flow inspect's inputs[] entries (taskName plus name); do not substitute the workflow-level input name for the node name. Obtain fileId from fkit file search --json, fkit ls --json, or fkit upload --json. If an existing template contains inputFiles bindings, put the required bindings in the CLI spec's inputs; you do not need to maintain two lists.

Bind I/O through inputs, not parameter overrides; file, file-group, and folder values must match the Flow port type and pattern. Do not put outputDir on individual tasks[] entries.

Job name rules

• The SPEC name field is the task name submitted to BioLine.
• If the user provides a name, use it as provided.
• If no name is provided, generate <YYYYMMDD-HHMMSS>-<flow/data-identifier>, for example 20261009-153045-fastp-megahit.
• Use the current time; keep the flow/data identifier to letters, digits, underscores, and hyphens.
• By default, set outputDir to the same value as the task name unless the user or Flow requires another directory.

outputDir must use the exact format returned by job template --json or a previously successful Job. Never guess /output/, /output/{name}, or another directory, and do not create an output directory with fkit mkdir. If the template does not establish a valid format, stop and report the missing platform contract.

Example: change sleep from 180 seconds to 30 seconds

First inspect the actual template to identify the node and parameter that control the delay, and verify that the saved value is "180". Replace <ACTUAL_NODE_NAME>, <ACTUAL_PARAM_KEY>, and <FLOW_VERSION_ID> below with query results; do not infer the node name or parameter key from the command sleep.

For a delay Flow without external inputs, the recommended job_spec.json is:

{
  "name": "20261016-120000-sleep",
  "flowVersionId": "<FLOW_VERSION_ID>",
  "outputDir": "20261016-120000-sleep",
  "inputs": [],
  "params": [
    {
      "taskName": "<ACTUAL_NODE_NAME>",
      "paramKey": "<ACTUAL_PARAM_KEY>",
      "paramValue": "30"
    }
  ]
}

This overrides the saved value "180" with "30" for this Job, without changing the published Flow. Supply actual inputs bindings if the selected Flow has external inputs.

Compatible form: tasks[].cmdParams

The same override can also be written under tasks[].cmdParams:

{
  "name": "20261016-120000-sleep",
  "flowVersionId": "<FLOW_VERSION_ID>",
  "outputDir": "20261016-120000-sleep",
  "inputs": [],
  "tasks": [
    {
      "name": "<ACTUAL_NODE_NAME>",
      "cmdParams": [
        {
          "paramKey": "<ACTUAL_PARAM_KEY>",
          "paramValue": "30",
          "isSelect": 1
        }
      ]
    }
  ]
}

• Match tasks[].name to the template's node name and cmdParams[].paramKey to a parameter on that node. Unknown nodes or parameter keys are errors.
• If the same node contains multiple entries with the same paramKey, include the actual template's index to disambiguate; do not guess an index.
• Nested overrides support paramValue (a string, including an empty string) and isSelect (0 means unselected, 1 means selected). Omitted fields keep their template values; null does not mean "keep the default." You may omit paramValue when changing only the selection state.
• The existing top-level params[] remains supported. If both forms target the same parameter, identical values can be merged, but conflicting overrides cause an error; their order does not determine which one wins. Usually use only one form.
• Parameter metadata such as type and prefix, commands, port connections, and node resources come from the server template. Local tasks does not replace the complete task graph. Leave I/O parameter entries unchanged when using a full template, and provide files through inputs.

Agent workflow

1. Resolve one exact Flow version with fkit flow list --json.
2. Read its ports, nodes, and parameters with fkit flow inspect --json.
3. Read the actual task template, saved parameters, and resources with fkit job template --json.
4. Locate and validate user files with fkit ls or fkit file search.
5. Write a compact job_spec.json from the query results, including inputs and any explicit parameter overrides.
6. Show one Job plan and wait for confirmation.
7. After confirmation run fkit job create <SPEC> --json.
8. Poll fkit job get <JOB_ID> --json; stop on failure instead of blindly resubmitting.
9. Return the Job ID, status, output directory, and external outputs. Hand downstream statistics, plotting, and reports to a separate skill.

Arguments and options

• --json — print machine-readable Job creation results.

Effect

A normal invocation submits a Job to BioLine. It does not modify a Flow or run local downstream analysis.

Output

A successful result includes the Job ID, name, Flow version, status, and output directory.

Read this page

Use --docs to read this page from BioLine's official AI documentation; --docs-json returns the JSON wrapper.