> ## Documentation Index > Fetch the complete documentation index at: https://filament.getgalaxy.io/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Manage local and deployed Filament from the command line 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} curl -fsSL https://getgalaxy.io/filament/install | sh ``` On macOS, you can also use Homebrew: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} brew install galaxy-io/tap/filament ``` Prebuilt binaries are available from [GitHub Releases](https://github.com/galaxy-io/filament/releases). Confirm the installation with `filament version`. ## Interactive mode Open the main menu in a terminal: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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 ` | Manage sources | | `filament sink ` | Manage sinks | | `filament pipeline ` | 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 ` | Manage targets | | `filament auth ` | Manage remote authentication | | `filament config ` | 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} --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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} filament source discover \ --source-connector postgres \ --source-connection-method url \ --source-dsn-env POSTGRES_DSN ``` ## Pipelines Create a pipeline from saved connections: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} filament up ``` The default address is `127.0.0.1:8080`. Run it in the background with: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```yaml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} 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.