CLI

The filament CLI manages connections, pipelines, and runs. It works against the local runtime or a deployed Filament server. A context selects the target, and most management commands work with both. The built-in local context needs no external services. It runs Filament in process with file-backed SQLite and an in-process event bus. State, secrets, run history, and checkpoints survive between commands.

Install

Run the install script on Linux or macOS:

curl -fsSL https://getgalaxy.io/filament/install | sh

On macOS, you can also use Homebrew:

brew install galaxy-io/tap/filament

Prebuilt binaries are available from GitHub Releases. Confirm the installation with filament version.

Interactive mode

Open the main menu in a terminal:

filament -i

The menu can create and manage connections and pipelines, discover resources, run pipelines, inspect run history, and edit local configuration. You can also open a specific wizard:

filament source create
filament sink create
filament pipeline create
filament run

Interactive mode is optional. Every operation also has flags for scripts and CI.

Commands

Command	What it does
`filament source <create\|edit\|list\|discover\|delete>`	Manage sources
`filament sink <create\|edit\|list\|delete>`	Manage sinks
`filament pipeline <create\|edit\|list\|delete>`	Manage pipelines
`filament run [pipeline]`	Run a saved pipeline or an inline transfer
`filament run list [pipeline]`	List run history
`filament up`	Keep the local runtime and web UI running
`filament down`	Stop a detached local runtime
`filament status`	Show the selected context and runtime
`filament context <add\|list\|current\|use\|rename\|delete>`	Manage targets
`filament auth <login\|status\|logout>`	Manage remote authentication
`filament config <path\|validate\|edit>`	Manage local YAML configuration

list can be shortened to ls, and context to ctx. Add --help after a command to see its flags. When a connector is selected, help also lists that connector’s fields. The global flags work in any position:

Flag	What it does
`--context NAME`	Use a context for one command
`--config PATH`	Use another local YAML file
`-i`, `--interactive`	Open interactive menus
`--layout boxed\|plain`	Select the table layout

Connections

Connector fields become flags with a source- or sink- prefix. Underscores become hyphens. For example, database_name becomes --source-database-name. Create two local connections:

filament source create production \
  --source-connector postgres \
  --source-connection-method url \
  --source-dsn-env POSTGRES_DSN

filament sink create warehouse \
  --sink-connector postgres \
  --sink-connection-method url \
  --sink-dsn-env POSTGRES_SINK_DSN

List them with filament source ls and filament sink ls. edit changes only the fields you pass. Use --unset source-FIELD or --unset sink-FIELD to remove an optional field. delete asks for confirmation unless you pass --force. A connection cannot be deleted while a pipeline uses it.

Secrets

Secret fields accept a value or an environment reference. These forms are equivalent in a local context:

--source-dsn-env POSTGRES_DSN
--source-dsn '$POSTGRES_DSN'
--source-dsn '${POSTGRES_DSN}'

The reference is stored as env:POSTGRES_DSN and resolved from the CLI’s environment when needed. Quote $NAME forms so the shell does not expand them first. References inside nested configuration are resolved too. On a remote context, secret references belong to the deployment’s secret provider; they do not read the CLI process’s environment. A secret value sent to the server is removed from connection configuration and stored by that provider.

Discover resources

Discover a saved source:

filament source discover production

The result shows resource names, primary keys, and estimated row counts. Use --refresh to bypass a cached discovery result. You can also discover without saving the source:

filament source discover \
  --source-connector postgres \
  --source-connection-method url \
  --source-dsn-env POSTGRES_DSN

Pipelines

Create a pipeline from saved connections:

filament pipeline create users-copy \
  --source production \
  --sink warehouse \
  --resources users,audit,logs \
  --sync-mode full \
  --write-mode replace

Leaving out --resources selects every resource discovered by the source. Available sync and write modes depend on the selected connectors. Pipeline-scoped connector fields use the same prefixes. For example, --sink-schema filament selects a destination schema. When a sink declares a schema, namespace, database, or key-prefix field and it is empty, the CLI uses the normalized source name.

Run pipelines

Run a saved pipeline on the selected context:

filament run users-copy

A saved pipeline without overrides runs on its target. Local runs keep history and checkpoints in SQLite. Remote runs execute in the deployment. The CLI streams progress until every run finishes. Inspect run history with:

filament run ls
filament run ls users-copy

List commands show 25 items by default. Use --limit to change the page size and the printed --next cursor to fetch the next page.

Direct local runs

An inline transfer runs locally without saving connections or a pipeline:

filament run \
  --source-connector postgres \
  --source-connection-method url \
  --source-dsn-env POSTGRES_DSN \
  --sink-connector stdout

Flags passed with a saved pipeline also create a direct local run. They can change resources, modes, or pipeline-scoped connector fields for that run. Direct runs support full reads only. They do not keep run history or checkpoints. Remote contexts run saved pipelines without overrides; edit the remote pipeline before running it when its configuration must change.

Local runtime

Normal local commands start the embedded runtime, perform one operation, and stop it. Use up to keep the API and web UI available:

filament up

The default address is 127.0.0.1:8080. Run it in the background with:

filament up --detach
filament status
filament down

filament up only accepts a local context. It uses the same SQLite database and secrets as other local commands.

Local configuration

The built-in local context reads ~/.config/filament/filament.yaml, or $XDG_CONFIG_HOME/filament/filament.yaml when XDG_CONFIG_HOME is set. filament config path prints the active path. The YAML file is a declarative input to the local runtime:

version: 1

sources:
  production:
    type: postgres
    config:
      connection_method: url
      dsn: env:POSTGRES_DSN

sinks:
  warehouse:
    type: stdout

pipelines:
  users-copy:
    source:
      ref: production
    sink:
      ref: warehouse
    resources:
      - users
    sync_mode: full
    write_mode: replace

The file is input, not an inventory. The CLI applies it when it changes and creates or updates the declared connections and pipelines. Removing an entry from YAML does not delete it from local state. Items created through the CLI or web app remain in SQLite and are not written back to YAML. Use filament config validate to check the file and filament config edit to open it in $VISUAL or $EDITOR. An invalid edit leaves a recovery file. Raw YAML commands apply only to local contexts.

Remote contexts

Add an unauthenticated deployment and select it:

filament context add production --server https://filament.example.com
filament context use production

Use --context production to select it for one command instead. filament status shows the active context and whether its server is reachable. For an authenticated deployment, log in with a service account:

filament --context production auth login \
  --server https://filament.example.com

The CLI prompts for the client ID and secret when they are not passed as flags. It verifies the credentials, creates and selects the context, and refreshes access tokens when needed. filament auth status shows the current state; filament auth logout removes the context’s credentials. Contexts and credentials are stored separately with owner-only permissions.

Output

Tables use the boxed layout by default. Select a plain layout with --layout plain or FILAMENT_LAYOUT=plain. A layout chosen from the interactive Settings menu is saved for later commands. Set NO_COLOR to disable terminal colors.

Get started

Concepts

Usage

Connectors

Deployment

API reference

Benchmarks

Contributing

Install

Interactive mode

Commands

Connections

Secrets

Discover resources

Pipelines

Run pipelines

Direct local runs

Local runtime

Local configuration

Remote contexts

Output

​Install

​Interactive mode

​Commands

​Connections

​Secrets

​Discover resources

​Pipelines

​Run pipelines

​Direct local runs

​Local runtime

​Local configuration

​Remote contexts

​Output

Install

Interactive mode

Commands

Connections

Secrets

Discover resources

Pipelines

Run pipelines

Direct local runs

Local runtime

Local configuration

Remote contexts

Output