CLI Usage#

fluvo#

Fluvo: A tool for importing, exporting, and processing data.

Usage

fluvo [OPTIONS] [COMMAND] [ARGS]...

Options

--version#: Show the version and exit.

-v, --verbose#: Enable verbose, debug-level logging.

--log-file <log_file>#: Path to a file to write logs to, in addition to the console.

--flow-file <flow_file>#: Path to the YAML flow file. Defaults to ‘flows.yml’ in current directory.

--run <flow_name>#: Run only these flows from the file (comma-separated names); default runs every flow in file order.

--var <NAME=VALUE>#: Override a flow variable (repeatable). Highest precedence: –var > env.* > the file’s vars block.

--dry-run#: Print the fully-resolved flow plan (the exact command per step) and exit without executing anything.

assess#

Assess a source Odoo for migration: inventory, volumes, and risk flags.

Usage

fluvo assess [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file (the source to assess).

--protocol <protocol>#

RPC protocol to use. Defaults to the config file’s, or xmlrpc.

Options:: xmlrpc | xmlrpcs | jsonrpc | jsonrpcs | json2 | json2s

--models <models>#: Comma-separated models to assess (e.g. ‘res.partner,product.template’). Omit to assess a curated default set of common migration models that exist on the database.

--output <output>#: Also write the report to this file (JSON, or Markdown with –format markdown) — a handout for a migration scoping conversation.

--format <report_format>#

Report format for the console (and –output).

Default:: 'table'
Options:: table | json | markdown

export#

Runs the data export process.

Usage

fluvo export [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--protocol <protocol>#

RPC protocol to use. Options: xmlrpc (default for Odoo 8-9), jsonrpc (recommended for Odoo 10-18, ~30%% faster), json2 (Odoo 19+, requires API key). If not specified, uses protocol from config file or defaults to xmlrpc.

Options:: xmlrpc | xmlrpcs | jsonrpc | jsonrpcs | json2 | json2s

--output <output>#: Required Output file path. A .parquet suffix writes Parquet; otherwise CSV.

--model <model>#: Required Odoo model to export from.

--fields <fields>#: Required Comma-separated list of fields to export. Special specifiers are available for IDs: ‘.id’ for raw database ID; ‘field/.id’ for related raw ID; ‘id’ for XML ID; ‘field/id’ for related XML ID. The tool automatically uses the best export method based on the fields requested.

--domain <domain>#: Odoo domain filter as a list string.

--worker <worker>#: Number of simultaneous connections.

--size <batch_size>#: Number of records to process per batch.

--streaming#: Enable streaming to write data batch-by-batch. Use for very large datasets.

--resume-session <resume_session>#: Resume a previously failed export session using its ID.

-s, --sep <separator>#: CSV separator character.

--context <context>#: Odoo context as a dictionary string.

--encoding <encoding>#: Encoding of the data file.

--technical-names#: Force the use of the high-performance raw export mode. This is often enabled automatically if you request raw IDs or technical field types like ‘selection’ or ‘binary’.

--all-companies#: Automatically set allowed_company_ids to all companies the user has access to. This enables exporting records across multiple companies.

--sudo#: Temporarily disable record rules for the model during export. Requires admin rights. Use with –all-companies to export all records across companies regardless of restrictive record rules.

--sanitize-newlines <sanitize_newlines>#: Replace embedded newlines in text fields with this string. Default: None (no sanitization). Recommended: “ | “ to prevent CSV corruption from embedded newlines in text/char/html fields.

--languages <languages>#: Comma-separated language codes (e.g. ‘nl_NL,fr_FR’) to export translations for. Every translatable field in –fields is emitted as an extra ‘field@lang’ column per language, alongside explicit ‘field@lang’ tokens. Requires an ‘id’ (or ‘.id’) column in –fields. Round-trips with ‘fluvo import’ (#282).

--since <TIMESTAMP>#: Weekly-delta: export only records changed since this timestamp (e.g. ‘2026-08-01’ or ‘2026-08-01 09:00:00’). Sugar that ANDs (write_date >= TIMESTAMP) onto –domain. Pair with ‘import –skip-unchanged’ for a re-runnable delta pipeline.

--since-field <since_field>#

The datetime field –since filters on (e.g. ‘create_date’).

Default:: 'write_date'

import#

Runs the data import process.

Usage

fluvo import [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--protocol <protocol>#

Options:: xmlrpc | xmlrpcs | jsonrpc | jsonrpcs | json2 | json2s

--file <filename>#: Required File to import — a .csv, or a .parquet source (read + type-coerced).

--model <model>#: Odoo model to import into. If not provided, it’s inferred from the filename.

--deferred-fields <deferred_fields>#: Comma-separated list of fields to defer to a second pass (enables two-pass import).

--auto-defer#: Automatically defer all non-required many2one fields. Enables progressive import where records are created first, then relational fields are populated in Pass 2.

--unique-id-field <unique_id_field>#: The column that uniquely identifies records (e.g., ‘xml_id’). Required for deferred imports.

--no-preflight-checks#: Skip all pre-flight checks before starting the import.

--check-refs <check_refs>#

Action for pre-import reference check: fail (abort if missing), warn (continue with warning), skip (no check). Default: warn.

Options:: fail | warn | skip

--worker <worker>#: Number of simultaneous connections.

--size <batch_size>#: Number of lines to import per connection.

--delay <batch_delay>#: Delay in seconds between batches to reduce server load. Use 0.5-2.0 for busy servers. Default: 0 (no delay).

--max-batch-bytes <max_batch_bytes>#: Maximum estimated payload size per batch in bytes. When a batch exceeds this size, it is split regardless of record count. Useful for imports with large binary fields like images. Default: 5242880 (5MB). Set to 0 to disable size-based batching.

--skip <skip>#: Number of initial lines to skip.

--fail#: Run in fail mode, retrying records from the _fail.csv file.

--headless#: Run in headless mode, auto-confirming any prompts (e.g., installing languages).

-s, --sep <separator>#: CSV separator character.

--groupby <groupby>#: Comma-separated list of columns to group data by to prevent deadlocks.Records with empty values for the first column are processed first, then grouped by that column. This process repeats for subsequent columns.

--auto-groupby#: Automatically pick a many2one column to group by (deadlock avoidance) when –groupby is not given. Chooses the relation with the most shared targets. Off by default.

--ignore <ignore>#: Comma-separated list of columns to ignore.

--context <context>#: Odoo context as a JSON string e.g., ‘{“key”: true}’.

--company-id <company_id>#: Company ID or external ID for multicompany imports. Accepts database ID (e.g., ‘1’) or XML ID (e.g., ‘base.main_company’). Sets allowed_company_ids context to enable cross-company field references.

--all-companies#: Automatically set allowed_company_ids to all companies the user has access to. This mimics the behavior of the Odoo web interface and enables importing records that reference data across multiple companies.

--allow-default-company#: For company-specific models on a multi-company database, proceed under the connecting user’s default company instead of aborting. By default such an import aborts unless –company-id or –all-companies is given, to prevent the most common silent migration error (wrong-company assignment). No effect on single-company databases.

--o2m#: Special handling for one-to-many imports.

--on-missing-ref <on_missing_ref>#: Action for missing references: field:action pairs. Actions: create (auto-create), skip (skip row), empty (set to False). Example: ‘country_id:create,user_id:skip,category_id:empty’

--auto-create-refs#: Automatically create missing related records for all many2one fields. Uses Odoo’s name_create to create records with just the name.

--set-empty-on-missing#: Set relational fields to empty (False) when reference not found, instead of failing the row. Useful for capturing incomplete data.

--fallback-values <fallback_values>#: Default values for invalid selection/boolean fields: field:value pairs. Example: ‘state:draft,active:true’

--tracking-disable, --tracking-enable#: Disable/enable mail tracking during import. Disabled by default.

--auto-clean#: Apply safe, type-aware coercions before load (strip whitespace, normalize null tokens, canonicalize booleans). Off by default.

--resolve-relation <resolve_relation_specs>#: Pre-resolve a relation column in Polars before load, so Odoo performs no name_search for it. Format ‘source_column:model:key_field:relation_field[:xmlid|dbid]’. Repeatable. Example: –resolve-relation country:res.country:code:country_id

--fix-missing-variants#: For product.template imports: create default variants for any imported templates that end up with none (Odoo’s load() does not auto-create them). Without this flag, fluvo only warns about them.

--allow-xmlid-collisions#: Proceed even when distinct source ids sanitize to the same Odoo external id (e.g. ‘a b’ and ‘a,b’ both become ‘a_b’). By default fluvo aborts, because Odoo’s load() would silently merge such rows into one record.

--m2m-mode <m2m_mode>#

How many2many fields are written in Pass 2. ‘replace’ makes each record’s set exactly the values in the file (single source of truth); ‘add’ only links the file’s values, leaving any pre-existing links intact.

Default:: 'replace'
Options:: replace | add

--no-cache#: Disable the on-disk id-map cache for this run (read and write). Use it after restoring/rebuilding the target database, when cached natural-key -> id mappings from a previous run may no longer be valid.

--defer-parent-store#: Defer parent_left/parent_right computation for hierarchical models. Improves performance for large imports of nested structures.

--encoding <encoding>#: Encoding of the data file.

--stream#: Stream CSV data without loading entire file into memory. Ideal for very large files. Not compatible with –o2m, –groupby, –defer, or –fail options.

--resume, --no-resume#: Resume from checkpoint if available. Enabled by default. When enabled, imports can be resumed after crashes or interruptions.

--no-checkpoint#: Disable checkpoint saving during import. Use for small imports where checkpointing overhead is not needed.

--dry-run#: Validate data without importing. Checks required fields, selection values, and reference existence.

--skip-unchanged#: Skip records that already exist with identical values. Makes imports idempotent by comparing field values before importing.

--skip-existing#: Skip records whose external ID already exists in Odoo. Makes imports safely re-runnable without update errors. Ideal for stock.quant and other models with update restrictions.

--adaptive-throttle, --no-adaptive-throttle#: Health-aware throttling that automatically adjusts batch sizes and delays based on server response times. Enabled by default to prevent server overload. Use –no-adaptive-throttle to disable for maximum speed.

--sudo#: Temporarily disable record rules for the model during import. Requires admin rights. Use with –all-companies to import all records across companies regardless of restrictive record rules.

--post-action <post_action>#: Method to call on imported records after successful import. Example: ‘action_apply_inventory’ for stock.quant to apply stock adjustments. The method is called with all successfully imported record IDs.

--move-date <move_date>#: Set the date on stock moves created by inventory adjustment. Use with –post-action action_apply_inventory for opening inventory imports. Format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. Example: –move-date 2026-01-01

migrate#

Performs a direct server-to-server data migration.

Usage

fluvo migrate [OPTIONS]

Options

--config-export <config_export>#: Required Path to the source Odoo connection config.

--config-import <config_import>#: Required Path to the destination Odoo connection config.

--model <model>#: Required The Odoo model to migrate.

--domain <domain>#: Domain filter to select records for export.

--fields <fields>#: Required Comma-separated list of fields to migrate.

--mapping <mapping>#: A dictionary string defining the transformation mapping.

--export-worker <export_worker>#: Number of workers for the export phase.

--export-batch-size <export_batch_size>#: Batch size for the export phase.

--import-worker <import_worker>#: Number of workers for the import phase.

--import-batch-size <import_batch_size>#: Batch size for the import phase.

module#

Commands for managing Odoo modules.

Usage

fluvo module [OPTIONS] COMMAND [ARGS]...

install#

Installs or upgrades a list of Odoo modules.

Usage

fluvo module install [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

-m, --modules <modules_str>#: Required A comma-separated list of module names to install or upgrade.

install-languages#

Installs one or more languages in the Odoo database.

Usage

fluvo module install-languages [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

-l, --languages <languages_str>#: Required A comma-separated list of language codes to install (e.g., ‘nl_BE,fr_FR’).

uninstall#

Uninstalls a list of Odoo modules.

Usage

fluvo module uninstall [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

-m, --modules <modules_str>#: Required A comma-separated list of module names to uninstall.

update-list#

Scans the addons path and updates the list of available modules.

Usage

fluvo module update-list [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

path-to-image#

Converts columns with local file paths into base64 strings.

Usage

fluvo path-to-image [OPTIONS] FILE

Options

-f, --fields <fields>#: Required Comma-separated list of fields to export. Special specifiers are available for IDs: ‘.id’ for the raw database ID of the record. ‘field/.id’ for the raw database ID of a related record. ‘id’ for the XML/External ID of the record. ‘field/id’ for the XML/External ID of a related record. Using ‘.id’ or ‘/.id’ will automatically enable a faster, raw export mode.

--path <path>#: Image path prefix. Defaults to the current working directory.

--out <out>#: Name of the resulting output file.

Arguments

FILE#: Required argument

url-to-image#

Downloads content from URLs in columns and converts to base64.

Usage

fluvo url-to-image [OPTIONS] FILE

Options

-f, --fields <fields>#: Required Comma-separated list of fields with URLs to convert to base64.

--out <out>#: Name of the resulting output file.

Arguments

FILE#: Required argument

vat#

Commands for managing VAT/VIES validation settings.

Usage

fluvo vat [OPTIONS] COMMAND [ARGS]...

disable#

Disable VAT validation (VIES and/or stdnum) for companies.

Usage

fluvo vat disable [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--company-ids <company_ids>#: Comma-separated list of company IDs. If not specified, disables for all.

--vies, --no-vies#: Disable VIES online check. Default: True.

--stdnum, --no-stdnum#: Disable stdnum format validation. Default: True.

--save-settings#: Save current settings for later restoration. Default: True.

--output <output>#: Save settings to a JSON file for later restoration.

get-settings#

Get current VAT validation settings for all companies.

Usage

fluvo vat get-settings [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--company-ids <company_ids>#: Comma-separated list of company IDs to check. If not specified, checks all.

--include-stdnum, --no-stdnum#: Include stdnum validation settings. Default: True.

restore#

Restore VAT validation settings to their original state.

Usage

fluvo vat restore [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--input <input_file>#: Restore settings from a JSON file saved by ‘vat disable –output’.

validate#

Validate VAT numbers against VIES in batches with optional notifications.

Usage

fluvo vat validate [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--batch-size <batch_size>#: Number of records to validate per batch. Default: 50.

--delay <delay>#: Delay between batches in seconds. Default: 1.0.

--notify-users <notify_users>#: Comma-separated list of user IDs to notify on failures.

--domain <domain>#: Odoo domain filter as a list string. Example: “[(‘is_company’, ‘=’, True)]”

--max-records <max_records>#: Maximum number of records to validate.

workflow#

Run legacy or complex post-import processing workflows.

Usage

fluvo workflow [OPTIONS] COMMAND [ARGS]...

create-missing-variants#

Create default variants for product.template records that have none.

Odoo auto-creates a default variant on ORM create, but the load() import API does not, so templates can import with no variants (#188). This finds them and creates the missing default variant.

Usage

fluvo workflow create-missing-variants [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--domain <domain>#: Optional Odoo domain (Python list literal) to scope which product templates are checked, e.g. “[(‘categ_id’, ‘=’, 5)]”.

--batch-size <batch_size>#

Number of variants to create per RPC call.

Default:: 200

--dry-run#: Only report how many templates lack variants; create nothing.

invoice-v9#

Runs the legacy Odoo v9 invoice processing workflow.

Usage

fluvo workflow invoice-v9 [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--action <actions>#

Workflow action to run. Can be specified multiple times. Defaults to ‘all’.

Options:: tax | validate | pay | proforma | rename | all

--field <field>#: Required The source field containing the legacy invoice status.

--status-map <status_map_str>#: Required Dictionary string mapping Odoo states to legacy states. e.g., “{‘open’: [‘OP’]}”

--paid-date-field <paid_date_field>#: Required The source field containing the payment date.

--payment-journal <payment_journal>#: Required The database ID of the payment journal.

--max-connection <max_connection>#: Number of parallel threads.

write#

Runs the batch update (write) process.

Usage

fluvo write [OPTIONS]

Options

--connection-file <connection_file>#: Required Path to the Odoo connection file.

--file <filename>#: Required File with records to update.

--model <model>#: Required Odoo model to write to.

--worker <worker>#: Number of simultaneous connections.

--size <batch_size>#: Number of records to process per batch.

--fail#: Run in fail mode, retrying records from the _write_fail.csv file.

-s, --sep <separator>#: CSV separator character.

--context <context>#: Odoo context as a dictionary string.

--encoding <encoding>#: Encoding of the data file.