oxo-flow init#
Initialize a new workflow project with a starter .oxoflow file, directory structure, and .gitignore.
Usage#
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
--jsonflag 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, andprovenance verify.
Examples#
Create a new project#
Create in a specific directory#
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.31.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
--forceis 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 --agentfollows the same rule: the three agent docs are only written when absent, so a re-init never overwrites a project owner'sAGENTS.mdedits (refresh explicitly withoxo-flow agent-docs --force)- The generated
.gitignoreincludes common bioinformatics file types and oxo-flow internal directories