Skip to content

oxo-flow init#

Initialize a new workflow project with a starter .oxoflow file, directory structure, and .gitignore.


Usage#

oxo-flow init [OPTIONS] <NAME>

Arguments#

Argument Description
<NAME> Project name (no path separators; also used as the default directory name)

Options#

Option Short Default Description
--dir -d ./<NAME> Output directory (defaults to the project name)
--force — off Overwrite an existing workflow file (its current contents are lost)
--agent — off Also scaffold agent docs: AGENTS.md, CLAUDE.md, and the full SKILL.md manual (agent-docs)
--verbose -v — Enable verbose (debug-level) logging
--quiet — — Suppress informational output (the version banner and scaffold listings are omitted; errors and warnings are unaffected)
--no-color — — Disable colored output

The global --json flag is not supported by this command — passing it fails fast instead of being silently ignored. Machine-readable output is available from: run, dry-run, validate, lint, test, status, batch, info, knowledge, schema, verify-data, license, ai, and provenance verify.


Examples#

Create a new project#

oxo-flow init my-pipeline

Create in a specific directory#

oxo-flow init my-pipeline -d /projects/genomics/my-pipeline

Create with agent docs (AI-operated projects)#

oxo-flow init my-pipeline --agent
# writes my-pipeline/AGENTS.md, CLAUDE.md, and SKILL.md alongside the workflow

AGENTS.md is an editable entry file (agent safety summary + project notes) that links to the full SKILL.md operating manual; CLAUDE.md imports it for Claude Code. See oxo-flow agent-docs for refreshing these files in an existing project.

Re-scaffold an existing project#

# Refuses while my-pipeline.oxoflow exists — nothing is touched:
oxo-flow init my-pipeline
# error: workflow file 'my-pipeline/my-pipeline.oxoflow' already exists.
#        Re-run with --force to overwrite it ...

# Explicit overwrite (your edits to the generated files are lost):
oxo-flow init my-pipeline --force

Output#

oxo-flow v0.32.0 — Rust-native bioinformatics pipeline engine
✓ Created new project at my-pipeline
  my-pipeline/my-pipeline.oxoflow
  my-pipeline/envs/example.yaml
  my-pipeline/scripts/example.sh
  my-pipeline/.gitignore

  Next steps: To run your first workflow:
    cd my-pipeline
    oxo-flow run my-pipeline.oxoflow

All output (including the version banner) goes to stderr; the banner appears only on an interactive terminal and is suppressed by --quiet.

Generated files#

<name>.oxoflow — Starter workflow file:

[workflow]
name = "my-pipeline"
version = "0.1.0"
description = "A new oxo-flow pipeline"
author = ""

[config]
# Variables defined here are used in shell commands as {config.key}
sample_name = "example"
greeting = "Hello from oxo-flow!"

[defaults]
threads = 1
memory = "1G"

[[rules]]
name = "hello_world"
description = "A minimal rule that writes a greeting"
output = ["results/{config.sample_name}_output.txt"]
# The greeting is passed via the environment, not spliced into the shell —
# an apostrophe or quote in the config value cannot break the command
# (`--arg greeting=...` overrides the default).
envvars = { GREETING = "{config.greeting}" }
shell = "echo \"$GREETING\" > {output[0]}"

envs/example.yaml — Starter conda environment specification.

scripts/example.sh — Starter helper script.

data/ — Pre-populated with an input.txt sample to allow immediate execution.

results/ — Empty directory created for workflow outputs.

.gitignore — Pre-configured with bioinformatics patterns (BAM, VCF, index files, workflow outputs).


Notes#

  • The output directory is created if it does not exist
  • If the workflow file already exists, oxo-flow refuses to run unless --force is given — a re-init can never silently destroy manual edits. With --force (or a fresh directory), the scaffold is regenerated; every other starter file (envs/example.yaml, scripts/example.sh, data/input.txt, .gitignore) is only written when absent, so existing files are always kept
  • --agent follows the same rule: the three agent docs are only written when absent, so a re-init never overwrites a project owner's AGENTS.md edits (refresh explicitly with oxo-flow agent-docs --force)
  • The generated .gitignore includes common bioinformatics file types and oxo-flow internal directories