Skip to main content

Documentation index: llms.txt. This page is also available as markdown: append .md to this URL or send Accept: text/markdown.

CLI Commands

Run coa --help at any time to see the current command list and global options for your installed version. Run coa <command> --help for flags specific to a subcommand. Use coa describe for built-in documentation that always matches your installed build.

$ coa [options] [command]​

Usage: coa [options] [command]

Options:
  -v, --version                   output the version number
  --verbose                       Show additional detail in command output
  --config <coa-config-location>  coa config file location
  --json                          Output machine-readable JSON instead of human-formatted text
  --no-color                      Disable colored output
  -h, --help                      display help for command

Local Development Commands:
  init      Interactive setup for a new local project
  run       Execute DML (insert/merge) for selected nodes
  create    Execute DDL (create/replace) for selected nodes
  install   Fetch and cache package contents
  validate  Validate YAML schemas and scan workspace for configuration problems
  describe  Explore CLI commands, schemas, and concepts
  doctor    Check config, auth, and warehouse access
  profile   Manage ~/.coa/config profiles and bind one to this workspace
  sources   Discover warehouse tables and scaffold source nodes

Cloud Operations:
  deploy           Apply a deployment plan to an environment
  plan             Diff workspace state against deployed state
  refresh          Run DML for selected nodes in a deployed environment
  rerun            Re-run a failed pipeline from the point of failure
  environments     List and manage deployment environments
  nodes            List and inspect deployed nodes
  jobs             List and inspect deployment jobs
  gitAccounts      Manage Git account connections
  workspace-nodes  List workspace node metadata
  projects         List and manage Coalesce projects
  runs             List and inspect pipeline runs
  cancel           Cancel a running pipeline
Local Development Commands Summary

These commands work against files in your Git checkout and execute SQL in your warehouse using workspaces.yml and ~/.coa/config. They do not replace environment-scoped coa refresh.

  • coa init

    Walks you through creating a new local project: project name, Coalesce domain, Snowflake credentials, Storage Location mappings, and default SQL Node scaffolding. Updates ~/.coa/config, data.yml, and workspaces.yml, runs coa install for selected Node Types, then runs coa doctor to report remaining issues.

    coa init

    If configuration files already exist, the command prompts before overwriting them. New projects created with coa init use SQL-first Node Types and do not install legacy default YAML Node Types, except source Nodes.

  • coa doctor

    Sanity-checks your config, connectivity, and project files. Run this after setting up or changing workspaces.yml or ~/.coa/config.

    coa doctor

  • coa profile

    Manages the connection profiles in ~/.coa/config and which one a Workspace runs on. list and show inspect them, create and set-cloud write them, use binds the current Workspace to one, and rename and delete maintain them. Once a Workspace is bound, the local commands above pick that profile without a --profile flag.

    coa profile list
    coa profile use prod

  • coa validate

    Runs workspace validation and scanners against your project files. Use this to catch structural issues before running.

    coa validate

  • coa describe

    Displays built-in documentation that matches your installed build. Topics include selectors, SQL annotations, Node Types, and more. For SQL-first Node authoring in the product, see SQL Node Type.

    coa describe
    coa describe selectors

    Use coa describe as the authoritative reference for your version rather than copying examples from external sources.

  • coa create

    Generates and applies DDL to create or update tables and views in your warehouse for selected Nodes.

    coa create
    coa create --all
    coa create --include <selector> --dry-run

    Supports --dry-run, --include, --exclude, --all, and --list-nodes where applicable. Selector syntax for local commands is documented in coa describe selectors and differs from the OR-keyword style used in coa refresh --include.

  • coa run

    Generates and applies DML to populate tables with data for selected Nodes.

    coa run
    coa run --include <selector>

    Uses the same selector style as coa create. See coa describe selectors for your version's syntax.

  • coa install

    Installs or syncs Coalesce Marketplace or packaged content when your workflow uses that command.

    coa install

    See coa install --help for options specific to your build.

  • coa sources

    Discovers warehouse tables for your Storage Locations and scaffolds source Node YAML under nodes/. Use list to inspect what is already imported, add to create source Nodes from the warehouse, and remove to delete files created by scaffolding.

    coa sources list
    coa sources list --location SRC
    coa sources add --location SRC
    coa sources add --location SRC --include 'ORDER*' --dry-run
    coa sources remove --location SRC --include 'OLD_*'

    Requires Coalesce CLI 7.35 or later. Database and schema on each source Node come from the Storage Mapping in workspaces.yml.

Cloud Operations Summary

These commands authenticate to Coalesce over HTTPS and require token, domain, and environmentID in your profile:

  • coa plan

    Generates coa-plan.json from the current directory or from --dir and your profile. Run this from the commit you intend to deploy.

    coa plan
    coa plan --profile databricksOAuthM2M
    coa plan --dir /path/to/repo

    The plan file captures Environment, Nodes, Jobs, and related metadata. Review it, but avoid hand-editing; change metadata in the Coalesce App or files, commit, and regenerate.

    For large projects, use --enableCache to speed up plan generation. Keep caching off unless plan time is a problem, and review how to speed up your deployments before enabling it.

    Common options: --profile, --environmentID, --platformKind, --parameters, --out, --gitsha, and warehouse credential overrides. Run coa plan -h for the full list.

  • coa deploy

    Applies an existing plan file to a Coalesce Environment. Defaults to ./coa-plan.json unless you pass --plan.

    coa deploy
    coa deploy --plan ./coa-plan.json --out deploy-results.json

    Returns run metadata including runType, runStatus, and runResults. Use --out to write JSON results to disk.

  • coa refresh

    Runs a Coalesce-managed refresh, typically DML, for an Environment that already has a successful deploy.

    coa refresh
    coa refresh --include '{ location: SAMPLE name: CUSTOMER } OR { location: SAMPLE name: LINEITEM }'
    coa refresh --jobID <id> --parallelism 8 --out refresh-results.json

    Supports --include, --exclude, --jobID, --parallelism, --parameters, --forceIgnoreEnvironmentStatus, and --out.

  • coa rerun

    Retries the failed Nodes from a previous refresh run. Pass the runID of the failed run. Runtime parameters from the original run are not preserved automatically; pass --parameters when you need a new map.

    coa rerun --runID <id>
    coa rerun --runID <id> --parameters '{"key":"value"}'

  • coa cancel

    Cancels an in-flight run by runID.

    coa cancel --runID <id>
API-Style Command Groups

These groups wrap REST-style operations for scripting and Automation. Each supports member commands such as list, get, create, put, and delete where applicable.

Command GroupCommon Subcommands
coa environmentslist, get, create, update, delete
coa nodeslist, get
coa runslist, get, list-results
coa workspace-nodeslist, create, get, put, delete

Additional groups ship with the product over time. Run coa --help to see your build's full list.

$ coa create [options]​

Execute DDL that creates or replaces objects for selected Nodes in your checked-out project. This runs against the warehouse the profile in --dir resolves to, not through Coalesce cloud. See Profiles.

coa create -h

Usage: coa create [options]

Execute DDL (create/replace) for selected nodes

Options:
  -d, --dir <dir>          Coalesce pipeline Yaml file path (default: ".")
  --include <selector>     Node selector syntax (e.g., '{ ORDERS }+', '{ name:
                           "CUSTOMER" }', '{ location: "SRC" }+')
  --exclude <selector>     Node selector syntax for excluding nodes (e.g., '{
                           TEST }', '{ location: "TEMP" }')
  --workspace <workspace>  Workspace name from workspaces.yml (e.g., dev,
                           prod). If not specified, defaults to 'dev'
  --list-nodes             List all available nodes (names and IDs) and exit
  --list-workspaces        List all available workspaces from workspaces.yml
                           and exit
  --dry-run                Preview which nodes would be affected without
                           executing. Use --verbose to see generated SQL
  -h, --help               display help for command

$ coa run [options]​

Execute DML that inserts or merges data for selected Nodes. Same Workspace and selector model as coa create.

coa run -h

Usage: coa run [options]

Execute DML (insert/merge) for selected nodes

Options:
  -d, --dir <dir>          Coalesce pipeline Yaml file path (default: ".")
  --include <selector>     Node selector syntax (e.g., '{ ORDERS }+', '{ name:
                           "CUSTOMER" }', '{ location: "SRC" }+')
  --exclude <selector>     Node selector syntax for excluding nodes (e.g., '{
                           TEST }', '{ location: "TEMP" }')
  --workspace <workspace>  Workspace name from workspaces.yml (e.g., dev,
                           prod). If not specified, defaults to 'dev'
  --list-nodes             List all available nodes (names and IDs) and exit
  --list-workspaces        List all available workspaces from workspaces.yml
                           and exit
  --dry-run                Preview which nodes would be affected without
                           executing. Use --verbose to see generated SQL
  -h, --help               display help for command

$ coa validate [options]​

Validate YAML schemas and run Workspace scanners for graph and structural checks.

coa validate -h

Usage: coa validate [options]

Validate YAML schemas and scan workspace for configuration problems

Options:
  -d, --dir <dir>          Root directory to scan for YAML files (default: ".")
  --include <selector>     Node selector to scope graph scanner results (e.g.,
                           '{ STG_ORDERS }', '{ location: "WORK" }'). Schema
                           validation always runs on all files.
  --exclude <selector>     Node selector to exclude from graph scanner results
  --workspace <workspace>  Workspace name from workspaces.yml (default: dev)
                           (default: "dev")
  -h, --help               display help for command

$ coa doctor [options]​

Check configuration, authentication, and warehouse access for a workspace.

coa doctor -h

Usage: coa doctor [options]

Check config, auth, and warehouse access

Options:
  -d, --dir <dir>    Coalesce pipeline YAML file path (default: ".")
  --profile <value>  Profile from ~/.coa/config
  --fix              Fix issues where possible (e.g., bootstrap missing
                     workspace.yml, update .gitignore)
  -h, --help         display help for command

The summary line names the profile the run used and what chose it, for example profile: prod (workspace.yml), so you can confirm you're checking the credentials you meant to. The cloud and connection sections then report on that profile. If the config file is missing or can't be read, the cloud and connection checks fail with that as the reason and the project file checks still run.

$ coa init [options]​

Set up a new local Coalesce project through an interactive questionnaire.

coa init -h

Usage: coa init [options]

Initialize local CLI config and project scaffolding

Options:
  -d, --dir <dir>                       Project directory (default: ".")
  --profile <value>                     Profile from ~/.coa/config
  --non-interactive                     Fail rather than prompt when a required
                                        value is missing. For agent/CI use.
  --domain <value>                      Coalesce domain (default:
                                        https://app.coalescesoftware.io)
  --token <value>                       Coalesce refresh token (paste from the
                                        app's Deploy tab)
  --environmentID <value>               Coalesce environment ID
  --platformKind <value>                Warehouse platform: Snowflake,
                                        Databricks, or BigQuery (default:
                                        Snowflake)
  --snowflakeAuthType <value>           Snowflake auth type: Basic, KeyPair, or
                                        OAuth (default: Basic)
  --snowflakeAccount <value>            Snowflake account
  --snowflakeUsername <value>           Snowflake username
  --snowflakePassword <value>           Snowflake password (Basic auth)
  --snowflakeKeyPairKey <value>         Path to Snowflake private key file
                                        (KeyPair auth)
  --snowflakeKeyPairPass <value>        Snowflake private key passphrase
                                        (KeyPair auth, optional)
  --snowflakeOAuthClientID <value>      Snowflake OAuth client id (OAuth auth,
                                        optional)
  --snowflakeOAuthClientSecret <value>  Snowflake OAuth client secret (OAuth
                                        auth, optional)
  --snowflakeOAuthRedirectUri <value>   Snowflake OAuth redirect URI (OAuth
                                        auth, optional)
  --snowflakeWarehouse <value>          Snowflake warehouse
  --snowflakeRole <value>               Snowflake role (optional)
  --databricksAuthType <value>          Databricks auth type: Token or OAuthM2M
                                        (default: Token)
  --databricksHost <value>              Databricks workspace host
  --databricksPath <value>              Databricks SQL warehouse HTTP path
  --databricksToken <value>             Databricks personal access token (Token
                                        auth)
  --databricksClientID <value>          Databricks client ID (OAuthM2M auth)
  --databricksClientSecret <value>      Databricks client secret (OAuthM2M
                                        auth)
  --bigQueryAuthType <value>            BigQuery auth type: ServiceAccount or
                                        ApplicationDefault (default:
                                        ServiceAccount)
  --bigQueryServiceAccountKey <value>   Path to BigQuery service-account JSON
                                        key (ServiceAccount auth)
  --bigQueryCredentialsFile <value>     Google credentials file overriding ADC
                                        discovery (ApplicationDefault auth,
                                        optional)
  --srcDatabase <value>                 SRC location database
  --srcSchema <value>                   SRC location schema
  --targetDatabase <value>              TARGET location database
  --targetSchema <value>                TARGET location schema
  --base-package <packageID>            Registry package ID of the base node
                                        types package to install (default: the
                                        platform's)
  --no-base-package                     Skip installing the platform's base
                                        node types package
  --skip-install                        Skip package hydration even if
                                        packages/ exists
  --skip-doctor                         Skip the final doctor verification step
  --force                               Re-prompt and overwrite even when
                                        existing values verify successfully
  --no-project                          Skip cloud project association (offline
                                        / pure-local scaffolding); by default
                                        init creates or links a project
  --project-id <id>                     Link this workspace to an existing
                                        cloud project id instead of creating
                                        one
  -h, --help                            display help for command

The questionnaire collects:

  • Project name
  • Coalesce domain - Choose a standard regional URL, for example North America, EMEA, or Canada, or enter a custom domain for PrivateLink or new regions
  • Warehouse credentials - The connection details for the platform you pass to --platformKind: Snowflake, Databricks, or BigQuery. Snowflake defaults to Basic authentication (username and password); --snowflakeAuthType selects KeyPair or OAuth instead. The command tests the connection before continuing, and writes no warehouse credentials if the test fails.
  • Storage Location mappings - Database and schema for SRC and TARGET locations

coa init writes the credentials it collects into a profile in ~/.coa/config. Without --profile it writes to the profile the directory already resolves to, which is [default] in a directory that names none. Pass --profile <name> to write into that profile instead and bind the Workspace to it, so later commands in the directory use it without the flag.

The two credential steps are written separately. Your token, domain, and Environment ID are saved to the profile as soon as they verify, before the warehouse step runs, so a run that fails at the warehouse leaves that much in place: fix the warehouse credentials and rerun rather than starting over. The Workspace binding is written last, after every step succeeds, so a failed run leaves the Workspace pointed where it was.

coa init refuses a profile whose platform disagrees with the Workspace: a Databricks profile in a Snowflake Workspace stops the run before anything is written. A data.yml with no platform recorded counts as Snowflake, and a directory with no data.yml yet is free to take any platform. Because coa init never rewrites an existing data.yml, changing the platform of a Workspace means editing that file yourself.

When setup finishes, coa init writes project files, runs coa install for the Node Types you select, and runs coa doctor. For an existing repository, create workspaces.yml manually or use coa doctor --fix instead. See Build Pipelines With the Coalesce CLI.

$ coa install [options]​

Download and cache Package contents for the Workspace. This uses Coalesce API credentials.

coa install -h

Usage: coa install [options]

Fetch and cache package contents

Options:
  --token <value>          Coalesce Refresh Token
  --domain <value>         Coalesce domain name to use for API requests
                           (default: "https://app.coalescesoftware.io")
  --profile <value>        Profile To Use
  -d, --dir <dir>          Workspace directory (default: ".")
  --workspace <workspace>  Workspace name from workspaces.yml (e.g., dev,
                           prod). If not specified, defaults to 'dev'
  -h, --help               display help for command

Like the other commands that act on a directory, coa install uses the profile the Workspace in --dir is bound to unless --profile overrides it. See Profiles.

$ coa describe [options] [topic] [subtopic]​

Print long-form help for commands, selectors, schemas, workflows, SQL annotations, and Node Types. Topics include commands, command, selectors, schemas, schema, workflow, structure, concepts, sql-format, and node-types. For topic command or schema, pass the command or schema name as subtopic. See SQL Node Type for documentation on SQL-first Node Types in Coalesce.

coa describe -h

Usage: coa describe [options] [topic] [subtopic]

Explore CLI commands, schemas, and concepts

Arguments:
  topic       Topic: commands, command, selectors, schemas, schema, workflow,
              structure, concepts, sql-format, node-types
  subtopic    Subtopic: command name (for 'command') or schema type (for
              'schema')

Options:
  -h, --help  display help for command

$ coa profile [options] [command]​

Manage the profiles in ~/.coa/config and bind one to a Workspace. A profile is a section of the config file holding Coalesce cloud auth and warehouse credentials. Binding a Workspace to a profile lets Workspaces on different platforms coexist on one machine without passing --profile to every command. See Profiles for the config file layout and resolution order.

Every command in this family accepts the global --config <path> to act on a config file other than ~/.coa/config, and --json to print machine-readable output for scripts and agents.

coa profile -h

Usage: coa profile [options] [command]

Manage ~/.coa/config profiles and bind one to this workspace

Options:
  -h, --help                         display help for command

Commands:
  list [options]                     Show the profiles in ~/.coa/config and
                                     which one this workspace uses
  show [options] <name>              Show one profile's fields, with secrets
                                     redacted
  create [options] <name>            Create a profile from warehouse
                                     credentials, verified before they are
                                     written
  set-cloud [options] <name>         Store Coalesce cloud auth (token, domain,
                                     environment) in a profile
  delete [options] <name>            Delete a profile from ~/.coa/config
  rename [options] <name> <newName>  Rename a profile, keeping its place in
                                     ~/.coa/config
  use [options] <name>               Bind this workspace to a profile
  unset [options]                    Remove this workspace's profile binding

coa profile list​

List every section of the config file with its platform and whether it carries cloud credentials, then report which profile a command run in --dir would use and why. Each row describes that section's own fields. To see what a profile resolves to after inheriting from [default], use coa profile show.

coa profile list -h

Usage: coa profile list [options]

Show the profiles in ~/.coa/config and which one this workspace uses

Options:
  -d, --dir <dir>    Workspace directory (default: ".")
  --profile <value>  Profile from ~/.coa/config
  -h, --help         display help for command
coa profile list
coa profile list -d ./my-workspace
coa profile list --json

coa profile show​

Print the named section's own fields alongside the effective profile the CLI composes from it, which is the section layered over [default]. Credentials are redacted in both.

coa profile show -h

Usage: coa profile show [options] <name>

Show one profile's fields, with secrets redacted

Arguments:
  name        Profile name — a section of ~/.coa/config

Options:
  -h, --help  display help for command
coa profile show default
coa profile show prod --json

coa profile create​

Collect warehouse credentials for one platform, run a live connection test, and write them to a new section of ~/.coa/config. Nothing is written unless the test passes, so a profile that appears in the config connected at least once. Every value is also accepted as a flag; pass --non-interactive to fail rather than prompt for a missing one.

This command configures the warehouse half of a profile. Coalesce cloud auth, token and domain, comes from coa profile set-cloud or from coa init. The name must be a new one: coa profile create refuses a profile that already exists and points you at coa init --profile <name>, which rewrites the credentials of one you have.

Profile names may contain letters, digits, spaces, and most punctuation. What's refused is anything the config file would read back as a different name: ., ;, #, ], and line breaks, along with an empty name and one that starts or ends with a space. The name is checked before you're prompted for anything and before the connection test runs.

coa profile create -h

Usage: coa profile create [options] <name>

Create a profile from warehouse credentials, verified before they are written

Arguments:
  name                                  Profile name — the new section of
                                        ~/.coa/config

Options:
  --platformKind <value>                Warehouse platform: Snowflake,
                                        Databricks, or BigQuery (default:
                                        Snowflake)
  --snowflakeAuthType <value>           Snowflake auth type: Basic, KeyPair, or
                                        OAuth (default: Basic)
  --snowflakeAccount <value>            Snowflake account
  --snowflakeUsername <value>           Snowflake username
  --snowflakePassword <value>           Snowflake password (Basic auth)
  --snowflakeKeyPairKey <value>         Path to Snowflake private key file
                                        (KeyPair auth)
  --snowflakeKeyPairPass <value>        Snowflake private key passphrase
                                        (KeyPair auth, optional)
  --snowflakeOAuthClientID <value>      Snowflake OAuth client id (OAuth auth,
                                        optional)
  --snowflakeOAuthClientSecret <value>  Snowflake OAuth client secret (OAuth
                                        auth, optional)
  --snowflakeOAuthRedirectUri <value>   Snowflake OAuth redirect URI (OAuth
                                        auth, optional)
  --snowflakeWarehouse <value>          Snowflake warehouse
  --snowflakeRole <value>               Snowflake role (optional)
  --databricksAuthType <value>          Databricks auth type: Token or OAuthM2M
                                        (default: Token)
  --databricksHost <value>              Databricks workspace host
  --databricksPath <value>              Databricks SQL warehouse HTTP path
  --databricksToken <value>             Databricks personal access token (Token
                                        auth)
  --databricksClientID <value>          Databricks client ID (OAuthM2M auth)
  --databricksClientSecret <value>      Databricks client secret (OAuthM2M
                                        auth)
  --bigQueryAuthType <value>            BigQuery auth type: ServiceAccount or
                                        ApplicationDefault (default:
                                        ServiceAccount)
  --bigQueryServiceAccountKey <value>   Path to BigQuery service-account JSON
                                        key (ServiceAccount auth)
  --bigQueryCredentialsFile <value>     Google credentials file overriding ADC
                                        discovery (ApplicationDefault auth,
                                        optional)
  --non-interactive                     Fail rather than prompt when a required
                                        value is missing. For agent/CI use.
  -h, --help                            display help for command
coa profile create staging --platformKind Snowflake
coa profile create dbx --non-interactive --platformKind Databricks --databricksHost <host> --databricksPath <path> --databricksToken <token>
coa profile create bq --non-interactive --platformKind BigQuery --bigQueryServiceAccountKey ./key.json

coa profile set-cloud​

Write the cloud half of a profile - the access token, the domain, and optionally the Environment ID - into a named section, leaving the rest of the config file as it was. The section is created if it isn't there yet, which makes this the way to add a cloud-only profile without running coa init. Omit --token to be prompted for one, or pass --non-interactive to fail instead.

coa profile set-cloud -h

Usage: coa profile set-cloud [options] <name>

Store Coalesce cloud auth (token, domain, environment) in a profile

Arguments:
  name                     Profile name — the section of ~/.coa/config to write
                           into

Options:
  -d, --dir <dir>          Workspace directory (default: ".")
  --token <value>          Coalesce refresh token
  --domain <value>         Coalesce domain to use for API requests (default:
                           https://app.coalescesoftware.io)
  --environmentID <value>  Environment ID to run against (optional)
  --non-interactive        Fail rather than prompt when a required value is
                           missing. For agent/CI use.
  -h, --help               display help for command

The command tells you which domain the profile ends up on and where that domain came from:

ReportWhat happened
domain set to <url>You passed --domain, and that value was written to the profile.
domain unchanged (<url>)The profile already stored a domain, and it was left alone.
domain inherited from [default] (<url>)The profile stores none, so it uses [default]'s. Nothing was written.
domain defaulted to <url>Neither the profile nor [default] stores one, so the standard Coalesce domain was written to the profile.

Because a call without --domain never overwrites a stored domain, you can rotate a token on a profile that points at a regional or PrivateLink domain without naming that domain again.

coa profile set-cloud prod --token <token>
coa profile set-cloud prod --token <token> --environmentID 42
coa profile set-cloud staging --non-interactive --token <token> --domain https://app.eu.coalescesoftware.io

coa profile use​

Bind the Workspace in --dir to a profile so every local command in that directory uses it without --profile. Coalesce Desktop follows the same binding when it opens the Workspace. The command refuses a profile whose platform does not match the Workspace, and it warns you when the profile carries no warehouse credentials. The binding is written to workspace.yml, is local to your machine, and is not committed.

coa profile use -h

Usage: coa profile use [options] <name>

Bind this workspace to a profile

Arguments:
  name             Profile name — a section of ~/.coa/config

Options:
  -d, --dir <dir>  Workspace directory (default: ".")
  -h, --help       display help for command
coa profile use prod
coa profile use bigquery-dev -d ./my-workspace

coa profile unset​

Remove the profile binding for this Workspace. Profile selection then falls back to the config file's own default profile setting, as it did before the Workspace was bound.

coa profile unset -h

Usage: coa profile unset [options]

Remove this workspace's profile binding

Options:
  -d, --dir <dir>  Workspace directory (default: ".")
  -h, --help       display help for command
coa profile unset
coa profile unset -d ./my-workspace

coa profile rename​

Rename a profile in place, keeping its position in the config file and everything written under it, comments included. default cannot be renamed, because every other profile inherits from it. If the Workspace in --dir is bound to the old name, the binding is rewritten to the new one. The new name has to be free and has to follow the same rules as a name you pass to coa profile create; nothing is moved to the backup file, because nothing is removed.

coa profile rename -h

Usage: coa profile rename [options] <name> <newName>

Rename a profile, keeping its place in ~/.coa/config

Arguments:
  name             Profile to rename
  newName          New profile name

Options:
  -d, --dir <dir>  Workspace directory (default: ".")
  -h, --help       display help for command
coa profile rename staging stage
coa profile rename old new -d ./my-workspace

coa profile delete​

Remove a profile from the config file. default cannot be deleted, because every other profile inherits from it. If the Workspace in --dir is bound to the deleted profile, the binding is removed too, so nothing is left pointing at a profile that no longer exists.

Before the section is removed it's appended to a backup file beside the config, ~/.coa/config.backup, with a timestamp and a note saying coa profile delete put it there. Credentials deleted by mistake are recoverable by copying the block back into ~/.coa/config. The backup holds real credentials and is readable only by you. If it can't be written, nothing is deleted.

coa profile delete -h

Usage: coa profile delete [options] <name>

Delete a profile from ~/.coa/config

Arguments:
  name             Profile name — a section of ~/.coa/config

Options:
  -d, --dir <dir>  Workspace directory (default: ".")
  -h, --help       display help for command
coa profile delete staging
coa profile delete old -d ./my-workspace

$ coa sources [options] [command]​

Discover warehouse tables for your Storage Locations and scaffold source Node YAML files under nodes/. Use list to inspect what exists, add to import, and remove to delete files created by scaffolding. These commands require Coalesce CLI 7.35 or later. They connect to your warehouse using the profile and Workspace configuration in ~/.coa/config and workspaces.yml.

coa sources -h

Usage: coa sources [options] [command]

Discover warehouse tables and scaffold source nodes

Options:
  -h, --help        display help for command

Commands:
  list [options]    Show locations and how many tables are already imported as
                    sources
  add [options]     Scaffold source node YAML files from warehouse tables
  remove [options]  Delete scaffolded source node YAML files

coa sources list​

Show Storage Locations and how many warehouse tables are already imported as source Nodes. Pass --location for per-table detail, including whether a source Node already exists.

coa sources list -h

Usage: coa sources list [options]

Show locations and how many tables are already imported as sources

Options:
  -d, --dir <dir>    Workspace directory (default: ".")
  --profile <value>  Profile from ~/.coa/config
  --location <name>  Scope to one storage location (show per-table detail)
  --all              Show every table across every location (can be large)
  --include <glob>   Filter tables by glob pattern (e.g. 'ORDER*')
  -h, --help         display help for command
coa sources list
coa sources list --location SRC
coa sources list --all --json
coa sources list --location SRC --include 'ORDER*'

coa sources add​

Scaffold source Node YAML from warehouse tables and write metadata under nodes/. Database and schema on each source Node come from the Storage Mapping for that location in workspaces.yml. On a TTY, running with no scope flags starts an interactive prompt. In non-interactive runs, pass --all or --location.

coa sources add -h

Usage: coa sources add [options]

Scaffold source node YAML files from warehouse tables

Options:
  -d, --dir <dir>    Workspace directory (default: ".")
  --profile <value>  Profile from ~/.coa/config
  --all              Import from every location (cannot combine with
                     --location)
  --location <name>  Import from one storage location
  --include <glob>   Filter tables by glob pattern (e.g. 'ORDER*')
  --overwrite        Also re-import tables that already have source nodes
                     (default: skip)
  --dry-run          List what would be imported without writing files
  -h, --help         display help for command
coa sources add
coa sources add --all
coa sources add --location SRC
coa sources add --location SRC --include 'ORDER*'
coa sources add --all --overwrite
coa sources add --all --dry-run

Use --dry-run to list the tables that would be imported without writing files. Use --overwrite only when you intend to re-import tables that already have source Nodes.

coa sources remove​

Delete source Node YAML files previously created by scaffolding from nodes/. Only files that match the scaffolding naming convention are removed. Hand-renamed files are left alone.

coa sources remove -h

Usage: coa sources remove [options]

Delete scaffolded source node YAML files

Options:
  -d, --dir <dir>    Workspace directory (default: ".")
  --all              Remove every scaffolded source node (cannot combine with
                     --location)
  --location <name>  Remove source nodes from one storage location
  --include <glob>   Filter tables by glob pattern (e.g. 'OLD_*')
  --yes              Skip confirmation prompt (non-TTY runs always skip)
  -h, --help         display help for command
coa sources remove
coa sources remove --location SRC --include 'OLD_*'
coa sources remove --all --yes

$ coa plan [options]​

Compare Workspace state in your Git checkout to deployed state and write a deployment plan file, coa-plan.json by default. Run coa plan from the directory that contains your Coalesce project files, or pass --dir.

During plan generation, Coalesce reports warnings for undefined {{ parameters... }} references. Warnings do not block writing coa-plan.json or running coa deploy. See Overwriting at Deploy for how the check works and how to fix warnings.

If you have a large project, --enableCache can speed up your deployments.

coa plan -h

Usage: coa plan [options]

Diff workspace state against deployed state

Options:
  --token <value>                      Coalesce Refresh Token
  --domain <value>                     Coalesce domain name to use for API
                                       requests (default:
                                       "https://app.coalescesoftware.io")
  --profile <value>                    Profile To Use
  --environmentID <value>              Environment ID
  --include <selector>                 Coalesce Node Selector
  --exclude <selector>                 Coalesce Node Selector
  --jobID <value>                      Coalesce JobID
  --parallelism <value>                Parallelism level to use
  --parameters <value>                 Parameters
  --platformKind <value>               Platform Kind (Snowflake, Databricks)
                                       (default: "Snowflake")
  --snowflakeAuthType <value>          Snowflake Auth Type (Basic, KeyPair)
  --snowflakeAccount <value>           Snowflake Account
  --snowflakeKeyPairKey <value>        Snowflake Key Pair Path
  --snowflakeKeyPairPass <value>       Snowflake Key Pair Pass
  --snowflakePassword <value>          Snowflake Password
  --snowflakeRole <value>              Snowflake Role
  --snowflakeUsername <value>          Snowflake Username
  --snowflakeWarehouse <value>         Snowflake Warehouse
  --snowflakeKeyPairPath <value>       Snowflake Key Pair Path (deprecated,
                                       please use --snowflakeKeyPairKey)
  --databricksAuthType <value>         Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>         Databricks Client ID
  --databricksClientSecret <value>     Databricks Client Secret
  --databricksHost <value>             Databricks Host URL
  --databricksPath <value>             Databricks Path
  --databricksToken <value>            Databricks Token
  --bigQueryAuthType <value>           BigQuery Auth Type (ServiceAccount)
  --bigQueryServiceAccountKey <value>  BigQuery Service Account Key Path
  --bigQueryClientEmail <value>        BigQuery Client Email
  -d, --dir <dir>                      Coalesce pipeline Yaml file path
                                       (default: ".")
  --out <plan-location>                Coalesce plan location (default:
                                       "./coa-plan.json")
  --gitsha <sha>                       Sets the git commit SHA shown in the
                                       plan manifest and UI. This does not
                                       affect which files are used—those come
                                       from the current directory or are set
                                       with the --dir parameter.
  --enableCache                        Enable caching to improve deploy plan
                                       generation times. Coalesce recommends
                                       keeping caching disabled unless you’re
                                       experiencing very long plan generation
                                       times. (default: false)
  -h, --help                           display help for command

$ coa deploy [options]​

Apply an existing coa-plan.json to an Environment. You must run coa plan first.

Deploy Results​

coa returns information about your run, including the following:

  • runType - Returns the type of run. deploy or refresh.
  • runStatus - The status of the run.
    • canceled
    • completed
    • failed
    • running
    • waitingToRun
  • runResults - Includes the SQL executed, any error details, and other environment information.

coa deploy -h

Usage: coa deploy [options]

Apply a deployment plan to an environment

Options:
  --token <value>                      Coalesce Refresh Token
  --domain <value>                     Coalesce domain name to use for API
                                       requests (default:
                                       "https://app.coalescesoftware.io")
  --profile <value>                    Profile To Use
  --environmentID <value>              Environment ID
  --platformKind <value>               Platform Kind (Snowflake, Databricks)
                                       (default: "Snowflake")
  --snowflakeAuthType <value>          Snowflake Auth Type (Basic, KeyPair)
  --snowflakeAccount <value>           Snowflake Account
  --snowflakeKeyPairKey <value>        Snowflake Key Pair Path
  --snowflakeKeyPairPass <value>       Snowflake Key Pair Pass
  --snowflakePassword <value>          Snowflake Password
  --snowflakeRole <value>              Snowflake Role
  --snowflakeUsername <value>          Snowflake Username
  --snowflakeWarehouse <value>         Snowflake Warehouse
  --snowflakeKeyPairPath <value>       Snowflake Key Pair Path (deprecated,
                                       please use --snowflakeKeyPairKey)
  --databricksAuthType <value>         Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>         Databricks Client ID
  --databricksClientSecret <value>     Databricks Client Secret
  --databricksHost <value>             Databricks Host URL
  --databricksPath <value>             Databricks Path
  --databricksToken <value>            Databricks Token
  --bigQueryAuthType <value>           BigQuery Auth Type (ServiceAccount)
  --bigQueryServiceAccountKey <value>  BigQuery Service Account Key Path
  --bigQueryClientEmail <value>        BigQuery Client Email
  -p, --plan <plan-location>           Coalesce plan location (default:
                                       "./coa-plan.json")
  -o, --out <output json>              Run Results Output in Json
  -h, --help                           display help for command

$ coa refresh [options]​

Run DML for selected Nodes in a deployed Coalesce Environment. A successful deploy must exist before refresh.

To re-run a failed refresh, use coa rerun <runID>. That only retries failed Nodes from the prior run.

Refresh Results​

coa returns information about your run, including the following:

  • runType - Returns the type of run. deploy or refresh.
  • runStatus - The status of the run.
    • canceled
    • completed
    • failed
    • running
    • waitingToRun
  • runResults - Includes the SQL executed, any error details, and other environment information.

coa refresh -h

Usage: coa refresh [options]

Run DML for selected nodes in a deployed environment

Options:
  --token <value>                      Coalesce Refresh Token
  --domain <value>                     Coalesce domain name to use for API
                                       requests (default:
                                       "https://app.coalescesoftware.io")
  --profile <value>                    Profile To Use
  --environmentID <value>              Environment ID
  --include <selector>                 Coalesce Node Selector
  --exclude <selector>                 Coalesce Node Selector
  --jobID <value>                      Coalesce JobID
  --parallelism <value>                Parallelism level to use
  --parameters <value>                 Parameters
  --platformKind <value>               Platform Kind (Snowflake, Databricks)
                                       (default: "Snowflake")
  --snowflakeAuthType <value>          Snowflake Auth Type (Basic, KeyPair)
  --snowflakeAccount <value>           Snowflake Account
  --snowflakeKeyPairKey <value>        Snowflake Key Pair Path
  --snowflakeKeyPairPass <value>       Snowflake Key Pair Pass
  --snowflakePassword <value>          Snowflake Password
  --snowflakeRole <value>              Snowflake Role
  --snowflakeUsername <value>          Snowflake Username
  --snowflakeWarehouse <value>         Snowflake Warehouse
  --snowflakeKeyPairPath <value>       Snowflake Key Pair Path (deprecated,
                                       please use --snowflakeKeyPairKey)
  --databricksAuthType <value>         Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>         Databricks Client ID
  --databricksClientSecret <value>     Databricks Client Secret
  --databricksHost <value>             Databricks Host URL
  --databricksPath <value>             Databricks Path
  --databricksToken <value>            Databricks Token
  --bigQueryAuthType <value>           BigQuery Auth Type (ServiceAccount)
  --bigQueryServiceAccountKey <value>  BigQuery Service Account Key Path
  --bigQueryClientEmail <value>        BigQuery Client Email
  -o, --out <output json>              Run Results Output in Json
  --forceIgnoreEnvironmentStatus       Ignore the environment status and
                                       refresh even if there is a failed
                                       deploy. This may cause refresh failures!
  -h, --help                           display help for command

$ coa rerun [options] <runID>​

Re-run a failed pipeline from the point of failure. Runtime parameters from the previous run are not preserved.

coa returns the same run fields as coa refresh: run type, status, and results.

coa rerun -h

Usage: coa rerun [options] <runID>

Re-run a failed pipeline from the point of failure

Arguments:
  runID                                The ID of the failed refresh to re-run

Options:
  --token <value>                      Coalesce Refresh Token
  --domain <value>                     Coalesce domain name to use for API
                                       requests (default:
                                       "https://app.coalescesoftware.io")
  --profile <value>                    Profile To Use
  --environmentID <value>              Environment ID
  --include <selector>                 Coalesce Node Selector
  --exclude <selector>                 Coalesce Node Selector
  --jobID <value>                      Coalesce JobID
  --parallelism <value>                Parallelism level to use
  --parameters <value>                 Parameters
  --platformKind <value>               Platform Kind (Snowflake, Databricks)
                                       (default: "Snowflake")
  --snowflakeAuthType <value>          Snowflake Auth Type (Basic, KeyPair)
  --snowflakeAccount <value>           Snowflake Account
  --snowflakeKeyPairKey <value>        Snowflake Key Pair Path
  --snowflakeKeyPairPass <value>       Snowflake Key Pair Pass
  --snowflakePassword <value>          Snowflake Password
  --snowflakeRole <value>              Snowflake Role
  --snowflakeUsername <value>          Snowflake Username
  --snowflakeWarehouse <value>         Snowflake Warehouse
  --snowflakeKeyPairPath <value>       Snowflake Key Pair Path (deprecated,
                                       please use --snowflakeKeyPairKey)
  --databricksAuthType <value>         Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>         Databricks Client ID
  --databricksClientSecret <value>     Databricks Client Secret
  --databricksHost <value>             Databricks Host URL
  --databricksPath <value>             Databricks Path
  --databricksToken <value>            Databricks Token
  --bigQueryAuthType <value>           BigQuery Auth Type (ServiceAccount)
  --bigQueryServiceAccountKey <value>  BigQuery Service Account Key Path
  --bigQueryClientEmail <value>        BigQuery Client Email
  -o, --out <output json>              Run Results Output in Json
  --forceIgnoreEnvironmentStatus       Ignore the environment status and
                                       refresh even if there is a failed
                                       deploy. This may cause refresh failures!
  -h, --help                           display help for command

$ coa environments [options] [command]​

List and manage deployment Environments through the Coalesce cloud API. Use create, update, and delete to provision and maintain Environments for coa plan and coa deploy. These commands require Coalesce 7.36 or later.

coa environments -h

Usage: coa environments [options] [command]

List and manage deployment environments

Options:
  -h, --help      display help for command

Commands:
  list [options]    List Environments
  get [options]     Get Environment
  create [options]  Create Environment
  update [options]  Update Environment
  delete [options]  Delete Environment
  help [command]    display help for command

coa environments list​

coa environments list -h

Usage: coa environments list [options]

List Environments

Options:
  --detail                 Include the full detail of the environments.
                           (default: false)
  --project <string>       Filter results to Environments in this Project ID
  --limit <integer>        The maximum number of environments to return.
                           (default: 100)
  --startingFrom <string>  The cursor point for paging the query results.
  --orderBy <string>       The field to order the results by. (default: "id")
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --paging                 Enable interactive paging
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

Use --project when you work in a multi-Project Org and need only the Environments for one Project. The server applies the filter before paging, so total and next match the filtered set.

coa environments get​

coa environments get -h

Usage: coa environments get [options]

Get Environment

Options:
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --environmentID <value>  Environment ID
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa environments create​

coa environments create -h

Usage: coa environments create [options]

Create Environment

Options:
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

An Environment belongs to a Coalesce Project. If you do not have a Project yet, run coa projects create first. Use coa environments list to read the new Environment ID for coa plan and coa deploy.

Pass a JSON request file with --inputFile. Required fields are project, name, and oauthEnabled. For Snowflake Projects, include connectionAccount. For Databricks Projects, include accessUrl.

Credentials and mappings

Create and update requests configure connection metadata only. Add warehouse passwords or OAuth refresh tokens in the Coalesce App under Build Settings > Environments > User Credentials after creation. Storage Mappings on deployed Environments are normally set when you deploy from a Workspace.

Example Snowflake create request file:

create-environment.json
{
  "project": "your-project-id",
  "name": "QA",
  "oauthEnabled": false,
  "connectionAccount": "xy12345.us-east-1",
  "description": "QA deployment target",
  "runTimeParameters": {
    "env": "qa"
  }
}

coa environments update​

coa environments update -h

Usage: coa environments update [options]

Update Environment

Options:
  --environmentID <value>     Environment ID
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

coa environments update sends a partial update to the Environment. Omitted fields stay unchanged. Set a field to null to clear nullable values such as accessUrl.

Example patch request file:

update-environment.json
{
  "name": "QA Updated",
  "description": "Updated QA deployment target",
  "runTimeParameters": {
    "env": "qa-updated"
  }
}

Run:

coa environments update --environmentID 6 --inputFile update-environment.json

See Update Environment in the API reference for the full request schema.

coa environments delete​

coa environments delete -h

Usage: coa environments delete [options]

Delete Environment

Options:
  --environmentID <value>  Environment ID
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

The command prompts for confirmation before it calls the API. Pass --skipConfirm to skip the prompt in Automation. Ensure the Environment has no active runs or dependent Job Schedules before you delete it.

$ coa nodes [options] [command]​

List and inspect deployed Nodes for an Environment.

coa nodes -h

Usage: coa nodes [options] [command]

List and inspect deployed nodes

Options:
  -h, --help      display help for command

Commands:
  list [options]  List Nodes
  get [options]   Get Node
  help [command]  display help for command

coa nodes list​

coa nodes list -h

Usage: coa nodes list [options]

List Nodes

Options:
  --detail                 Include the full detail of the nodes. (default:
                           false)
  --limit <integer>        The maximum number of nodes to return. (default:
                           100)
  --startingFrom <string>  The cursor point for paging the query results.
  --orderBy <string>       The field to order the results by. (default: "id")
  --skipParsing            Skip parsing column references and updating sources
                           for the nodes. (default: false)
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --environmentID <value>  Environment ID
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --paging                 Enable interactive paging
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa nodes get​

coa nodes get -h

Usage: coa nodes get [options]

Get Node

Options:
  --nodeID <string>        The node ID.
  --skipParsing            Skip parsing column references and updating sources
                           for the nodes. (default: false)
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --environmentID <value>  Environment ID
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

$ coa jobs [options] [command]​

Inspect deployment jobs.

coa jobs -h

Usage: coa jobs [options] [command]

List and inspect deployment jobs

Options:
  -h, --help      display help for command

Commands:
  get [options]   Get Job
  help [command]  display help for command

coa jobs get​

coa jobs get -h

Usage: coa jobs get [options]

Get Job

Options:
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --environmentID <value>  Environment ID
  --jobID <value>          Coalesce JobID
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

$ coa gitAccounts [options] [command]​

Manage Git account connections for your organization.

coa gitAccounts -h

Usage: coa gitAccounts [options] [command]

Manage Git account connections

Options:
  -h, --help        display help for command

Commands:
  list [options]    List all org git accounts
  create [options]  Create a git account
  get [options]     Get a single git account
  delete [options]  Delete a single git account
  update [options]  Update a single git account
  help [command]    display help for command

coa gitAccounts list​

coa gitAccounts list -h

Usage: coa gitAccounts list [options]

List all org git accounts

Options:
  --accountOwner <string>  The owner of the git accounts. If not provided will
                           fallback to the requester's accounts.
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa gitAccounts create​

coa gitAccounts create -h

Usage: coa gitAccounts create [options]

Create a git account

Options:
  --accountOwner <string>     The owner of the git accounts. If not provided
                              will fallback to the requester's accounts.
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

coa gitAccounts get​

coa gitAccounts get -h

Usage: coa gitAccounts get [options]

Get a single git account

Options:
  --gitAccountID <string>  The git account ID.
  --accountOwner <string>  The owner of the git accounts. If not provided will
                           fallback to the requester's accounts.
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa gitAccounts delete​

coa gitAccounts delete -h

Usage: coa gitAccounts delete [options]

Delete a single git account

Options:
  --gitAccountID <string>  The git account ID.
  --accountOwner <string>  The owner of the git accounts. If not provided will
                           fallback to the requester's accounts.
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa gitAccounts update​

coa gitAccounts update -h

Usage: coa gitAccounts update [options]

Update a single git account

Options:
  --gitAccountID <string>     The git account ID.
  --accountOwner <string>     The owner of the git accounts. If not provided
                              will fallback to the requester's accounts.
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

$ coa workspace-nodes [options] [command]​

List and mutate workspace Node metadata through the Coalesce API. For field shapes used by create and update, see Create Node and Set Node.

coa workspace-nodes -h

Usage: coa workspace-nodes [options] [command]

List workspace node metadata

Options:
  -h, --help        display help for command

Commands:
  list [options]    List Workspace Nodes
  create [options]  Create Node
  get [options]     Get Node
  put [options]     Set Node
  delete [options]  Delete Node
  help [command]    display help for command

coa workspace-nodes list​

coa workspace-nodes list -h

Usage: coa workspace-nodes list [options]

List Workspace Nodes

Options:
  --workspaceID <string>   The workspace ID.
  --detail                 Include the full detail of the nodes. (default:
                           false)
  --limit <integer>        The maximum number of nodes to return. (default:
                           100)
  --startingFrom <string>  The cursor point for paging the query results.
  --orderBy <string>       The field to order the results by. (default: "id")
  --skipParsing            Skip parsing column references and updating sources
                           for the nodes. (default: false)
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --paging                 Enable interactive paging
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa workspace-nodes create​

coa workspace-nodes create -h

Usage: coa workspace-nodes create [options]

Create Node

Options:
  --workspaceID <string>      The workspace ID.
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

coa workspace-nodes get​

coa workspace-nodes get -h

Usage: coa workspace-nodes get [options]

Get Node

Options:
  --workspaceID <string>   The environment ID.
  --nodeID <string>        The node ID.
  --skipParsing            Skip parsing column references and updating sources
                           for the nodes. (default: false)
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa workspace-nodes put​

coa workspace-nodes put -h

Usage: coa workspace-nodes put [options]

Set Node

Options:
  --workspaceID <string>      The environment ID.
  --nodeID <string>           The node ID.
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

coa workspace-nodes delete​

coa workspace-nodes delete -h

Usage: coa workspace-nodes delete [options]

Delete Node

Options:
  --workspaceID <string>  The environment ID.
  --nodeID <string>       The node ID.
  --profile <value>       Profile To Use
  --token <value>         Coalesce Refresh Token
  --skipConfirm           Skip any confirmation prompts
  -h, --help              display help for command

$ coa projects [options] [command]​

List and manage Coalesce projects.

coa projects -h

Usage: coa projects [options] [command]

List and manage Coalesce projects

Options:
  -h, --help        display help for command

Commands:
  list [options]    Get Projects
  create [options]  Create Project
  get [options]     Get Project
  delete [options]  Delete Project
  update [options]  Update a project
  help [command]    display help for command

coa projects list​

coa projects list -h

Usage: coa projects list [options]

Get Projects

Options:
  --includeWorkspaces      Whether or not to include nested workspace data for
                           all projects.
  --includeJobs            Whether or not to include nested job data for all
                           workspaces in the projects.
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa projects create​

coa projects create -h

Usage: coa projects create [options]

Create Project

Options:
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

coa projects get​

coa projects get -h

Usage: coa projects get [options]

Get Project

Options:
  --projectID <string>     The project ID.
  --includeWorkspaces      Whether or not to include nested workspace data for
                           all projects.
  --includeJobs            Whether or not to include nested job data for all
                           workspaces in the projects.
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa projects delete​

coa projects delete -h

Usage: coa projects delete [options]

Delete Project

Options:
  --projectID <string>        The project ID.
  --includeWorkspaces         Whether or not to include nested workspace data
                              for all projects.
  --includeJobs               Whether or not to include nested job data for all
                              workspaces in the projects.
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

coa projects update​

coa projects update -h

Usage: coa projects update [options]

Update a project

Options:
  --projectID <string>        The project ID.
  --includeWorkspaces         Whether or not to include nested workspace data
                              for all projects.
  --includeJobs               Whether or not to include nested job data for all
                              workspaces in the projects.
  --profile <value>           Profile To Use
  --token <value>             Coalesce Refresh Token
  --inputFile <request-file>  The request content
  --outputFile <fileName>     Write output to file
  --format <json|text>        Output results as JSON or text (choices: "json",
                              "text", default: "text")
  --skipConfirm               Skip any confirmation prompts
  -h, --help                  display help for command

$ coa runs [options] [command]​

List and inspect pipeline runs.

coa runs -h

Usage: coa runs [options] [command]

List and inspect pipeline runs

Options:
  -h, --help              display help for command

Commands:
  list [options]          List Runs
  get [options]           Get Run
  list-results [options]  List Run Results
  help [command]          display help for command

coa runs list​

coa runs list -h

Usage: coa runs list [options]

List Runs

Options:
  --limit <integer>                The maximum number of runs to return.
                                   (default: 25)
  --startingFrom <integer|string>  The starting run ID, runStartTime, or
                                   runEndTime (exclusive) for paging the query
                                   results.
  --orderBy <string>               The field used to sort query results.
                                   Defaults to `id`, but must be explicitly
                                   provided when also using `startingFrom`.
                                   Make sure to match data type.
  --orderByDirection <string>      The sort order for query results. (default:
                                   "desc")
  --projectID <string|array>       One or more project IDs to filter the query
                                   results.
  --runType <string|array>         One or more run types to filter the query
                                   results.
  --runStatus <string|array>       One or more status values to filter the
                                   query results.
  --detail                         Include the full detail of the run.
                                   (default: false)
  --profile <value>                Profile To Use
  --token <value>                  Coalesce Refresh Token
  --environmentID <value>        Environment ID
  --allEnvironments                Include all environments
  --outputFile <fileName>          Write output to file
  --format <json|text>             Output results as JSON or text (choices:
                                   "json", "text", default: "text")
  --paging                         Enable interactive paging
  --skipConfirm                    Skip any confirmation prompts
  -h, --help                       display help for command

coa runs get​

coa runs get -h

Usage: coa runs get [options]

Get Run

Options:
  --runID <integer>        The run ID.
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

coa runs list-results​

coa runs list-results -h

Usage: coa runs list-results [options]

List Run Results

Options:
  --runID <integer>        The run ID.
  --profile <value>        Profile To Use
  --token <value>          Coalesce Refresh Token
  --outputFile <fileName>  Write output to file
  --format <json|text>     Output results as JSON or text (choices: "json",
                           "text", default: "text")
  --skipConfirm            Skip any confirmation prompts
  -h, --help               display help for command

$ coa cancel [options] <runID>​

Cancel a running pipeline.

coa cancel -h

Usage: coa cancel [options] <runID>

Cancel a running pipeline

Arguments:
  runID                    The ID of the run to cancel.

Options:
  --token <value>          Coalesce Refresh Token
  --domain <value>         Coalesce domain name to use for API requests
                           (default: "https://app.coalescesoftware.io")
  --profile <value>        Profile To Use
  --environmentID <value>  Environment ID
  -h, --help               display help for command

Parallelism Limits​

The --parallelism parameter on coa refresh controls how many Nodes run concurrently against your warehouse. REST refresh APIs cap parallelism at 64; the CLI refresh path is not capped the same way. Choose a value your warehouse can sustain.

Overwriting Defaults​

You can override values from your coa config by passing flags on the command line or by setting the same fields on API requests you send yourself.

Using Include and Exclude​

Cloud commands such as coa plan, coa refresh, and coa rerun use the same Selector Queries model as the Coalesce App. Local coa create, coa run, and coa validate accept selector strings on --include and --exclude. Run coa describe selectors for the exact syntax your build supports.

coa refresh example with include flag
coa refresh --include '{ location: SAMPLE name: CUSTOMER } OR { location: SAMPLE name: LINEITEM } OR { location: SAMPLE name: NATION } OR { location: SAMPLE name: ORDERS } OR { location: SAMPLE name: PART } OR { location: SAMPLE name: PARTSUPP } OR { location: SAMPLE name: REGION } OR { location: SAMPLE name: SUPPLIER } OR { location: QA name: STG_PARTSUPP } OR { location: PROD name: STG_PARTSUPP }'

Selectors​

coa refresh --include and --exclude​

The --include and --exclude flags for coa refresh use the OR keyword, not ||, to separate selector expressions:

coa refresh --include '{ location: SAMPLE name: CUSTOMER } OR { location: SAMPLE name: LINEITEM } OR { location: SAMPLE name: NATION }'

Full selector syntax is documented in Selector Queries.

Local Commands for Create and Run​

Selector syntax for local commands differs from the OR-keyword style used in coa refresh. Open coa describe selectors and follow the examples for your installed version rather than copying snippets across contexts.

What's Next?​