CLI Reference

Installing Ciaren (pip install ciaren, or pip install -e . from a source checkout) exposes a ciaren command — the setup surface for running and configuring Ciaren. It uses only the standard library, so there's nothing extra to install.

ciaren --help
ciaren --version

ciaren serve

Run the API server and the background scheduler in a single process (no broker, no extra services). This is the recommended way to start Ciaren.

ciaren serve
ciaren serve --port 8001 --reload
ciaren serve --engine pandas --execution-mode process
ciaren serve --no-scheduler

Flags are translated into the matching environment variables before the app is imported, so they take precedence over your .env.

Pointing at a specific env file

By default Ciaren reads ./.env. Use --env-file to load a different file (for example a per-environment config) before settings are resolved:

ciaren serve --env-file /etc/ciaren/production.env

Precedence is flags > existing environment variables > --env-file > defaults, so values already exported in your shell are not overridden by the file. The same flag works on ciaren info and ciaren check, which is handy for inspecting or validating a specific config:

ciaren info  --env-file /etc/ciaren/production.env
ciaren check --env-file /etc/ciaren/production.env

ciaren init

Write a commented starter .env to get going quickly.

ciaren init                 # writes ./.env
ciaren init --path .env.local
ciaren init --force         # overwrite an existing file
ciaren init --no-ml         # skip provisioning the default local MLflow directory

ciaren info

Print the resolved configuration the server would use (the database password is redacted). Handy for confirming which .env / env vars are in effect. Note: values overridden from the Settings page live in the database and take precedence once the server is running; ciaren info shows the environment-level resolution only.

ciaren info

Ciaren resolved configuration:
  environment          development
  database_url         sqlite+aiosqlite:///./ciaren.db
  data_dir             /path/to/.data
  default_engine       polars
  execution_mode       thread
  scheduler_enabled    True
  ...

ciaren check

Validate the environment and exit non-zero on failure — useful in setup scripts and CI. It checks that:

• the data directory is writable,
• the database URL uses an async driver,
• the database is reachable,
• the dataframe engines are importable, and
• (Windows) the MLflow tracking path is short enough to log models under the 260-character path limit — see the ml_path line below.

ciaren check

[ok]   data_dir: /path/to/.data
[ok]   async_driver: sqlite+aiosqlite:///./ciaren.db
[ok]   database: reachable
[ok]   engines: pandas, polars
[ok]   ml: enabled, tracking=./mlruns

All checks passed.

Both info and check accept --output json for scripting and CI:

ciaren info --output json
ciaren check --output json   # {"ok": true, "checks": [...]}; exit 1 on failure

ciaren db

Manage the database schema through Alembic migrations. This is the production-grade path: it versions the schema and applies changes in order, across SQLite, PostgreSQL, and MySQL.

ciaren db upgrade            # apply all migrations up to the latest revision
ciaren db upgrade --revision <id>
ciaren db current            # show the revision the database is stamped at
ciaren db reset --yes        # DROP every table and rebuild from migrations

All three accept --env-file so you can target a specific environment's config.

Recommended production flow

1. Set CIAREN_DATABASE_URL to your async Postgres/MySQL URL.
2. Run ciaren db upgrade as part of each deploy (before starting the app).
3. Start the server with ciaren serve.

ciaren transformations

Inspect the transformation node types the engine supports — the same set the visual editor exposes.

ciaren transformations list
ciaren transformations list --output json

66 transformation node types:
  assertExpression   inputs=1
  assertNotNull      inputs=1
  assertRowCount     inputs=1
  ...

ciaren flow

Validate and migrate .flow document files — the portable, versioned description of a flow. Useful in CI to catch a malformed or outdated project before importing it.

ciaren flow validate project.flow              # schema + graph structure
ciaren flow validate project.flow --output json
ciaren flow migrate  project.flow              # print the document migrated to the current schema version
ciaren flow migrate  project.flow --to 3       # target a specific schema version instead of the latest
ciaren flow migrate  project.flow --write      # write back (keeps a .bak)

ciaren secret

Manage connection secrets in the OS keychain (Windows Credential Manager, macOS Keychain, Secret Service on Linux desktops) — the recommended secret source on a desktop install. Requires the optional extra:

pip install ciaren[keyring]

Then:

ciaren secret set pg-main      # prompts for the value (hidden, confirmed)
ciaren secret unset pg-main    # removes it from the keychain

Headless servers and containers have no keychain daemon — use env: or file: references there.

A stored secret is referenced from a connection's secret field as keyring:pg-main. The value never touches Ciaren's database, the API, or your shell history — see Connections for the full secret-reference model (env:, keyring:, file:).

Plugin tooling: ciaren-plugin

Installing, inspecting, and (for publishers) signing plugins is a separate command — ciaren-plugin, from the same ciaren distribution — so the everyday ciaren CLI doesn't carry the plugin-authoring surface. See the Plugin CLI Reference for every subcommand, and Packaging & Distribution for the full publishing workflow.

ciaren-plugin list                          # discovered plugins + status
ciaren-plugin install my-plugin.ciarenplugin    # verify + install
ciaren-plugin enable acme.myplugin

Running the old ciaren plugin ... form prints a pointer to the new command.

Environment variables

All settings use the CIAREN_ prefix and can be set via the environment or a .env file in the backend directory.

See also

• Installation — first-time setup
• Engines — --engine, --execution-mode, run timeouts
• Scheduling — the background scheduler