Skip to main content

CLI Commands

$ coa [options] [command]​

Usage: coa [options] [command]

Options:
  -v, --version                               output the version number
  -b, --debug                                 Output extra debugging (default: false)
  --verbose                                   Log more verbosely (default: false)
  --config <coa-config-location>              coa config file location
   --changeLogLevel <loggingArea>:<logLevel>  INTERNAL:Change logging level of logging area (default:
                                              false)
  -h, --help                                  display help for command

Commands:
  deploy [options]                            run a coalesce deployment plan
  plan [options]                              plan a Coalesce deployment
  refresh [options]                           runs a Coalesce pipeline
  rerun [options] <runID>                     re-runs a failed Coalesce pipeline. Runtime parameters from
                                              the previous run will not be preserved.
  environments                                Environments
  nodes                                       Nodes
  jobs                                        Jobs
  gitAccounts                                 Git account management
  workspace-nodes                             Nodes
  projects                                    Projects
  runs                                        Runs
  cancel [options] <runID>                    Cancels a running pipeline.
  help [command]                              display help for command

$ coa plan [options]​

Generate a coa-plan.json file that can be deployed.

Run coa plan in the same directory as the locally cloned copy of your Coalesce project's Git repository.

Caching Deployment Plan

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

Flags

coa plan -h

plan a Coalesce deployment

Options:
  --domain <value>                  Coalesce domain name to use for API requests
                                    (default: "https://app.coalescesoftware.io")
  --environmentID <value>           Environment ID
  --exclude <value>                 Coalesce Node Selector
  --include <value>                 Coalesce Node Selector
  --jobID <value>                   Coalesce JobID
  --parallelism <value>             Parallelism level to use
  --parameters <value>              Parameters
  --platformKind <value>            Platform Kind (Snowflake, Databricks) (default:
                                    "Snowflake")
  --profile <value>                 Profile To Use
  --token <value>                   Coalesce Refresh Token
  --databricksAuthType <value>      Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>      Databricks Client ID
  --databricksClientSecret <value>  Databricks Client Secret
  --databricksPath <value>          Databricks Path
  --databricksToken <value>         Databricks Token
  --snowflakeAuthType <value>       Snowflake Auth Type (Basic, KeyPair)
  --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)
  -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]​

Run an existing coa-plan.json. You must create a plan, before you can deploy.

Deploy is used to make structural changes to the data warehouse (typically DDL commands) and save the corresponding data warehouse configuration for the environment for subsequent refreshes. See Deployment and Refresh for information on deployment.

Deploy results

The coa will return 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.

Flags

coa deploy -h

  • Include and exclude are only used for refresh.

run a coalesce deployment plan

Options:
  --domain <value>                  Coalesce domain name to use for API requests (default:
                                    "https://app.coalescesoftware.io")
  --environmentID <value>           Environment ID
  --exclude <value>                 Coalesce Node Selector
  --include <value>                 Coalesce Node Selector
  --jobID <value>                   Coalesce JobID
  --parallelism <value>             Parallelism level to use
  --parameters <value>              Parameters
  --platformKind <value>            Platform Kind (Snowflake, Databricks) (default: "Snowflake")
  --profile <value>                 Profile To Use
  --token <value>                   Coalesce Refresh Token
  --databricksAuthType <value>      Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>      Databricks Client ID
  --databricksClientSecret <value>  Databricks Client Secret
  --databricksPath <value>          Databricks Path
  --databricksToken <value>         Databricks Token
  --snowflakeAuthType <value>       Snowflake Auth Type (Basic, KeyPair)
  --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)
  -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]​

Refresh is used to run data transformations, typically DML commands (Merge, Insert, Truncate, etc). See Deployment and Refresh for information on refresh. That deployment must happen on a environment before refresh is possible.

To re-run a failed refresh use:
coa rerun <runID>

This only works on failed refreshes, and only the nodes that previously failed will be run.

Refresh results

coa will return 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.

Flags

coa refresh -h

runs a Coalesce pipeline

Options:
  --domain <value>                  Coalesce domain name to use for API requests (default:
                                    "https://app.coalescesoftware.io")
  --environmentID <value>           Environment ID
  --exclude <value>                 Coalesce Node Selector
  --include <value>                 Coalesce Node Selector
  --jobID <value>                   Coalesce JobID
  --parallelism <value>             Parallelism level to use
  --parameters <value>              Parameters
  --platformKind <value>            Platform Kind (Snowflake, Databricks) (default: "Snowflake")
  --profile <value>                 Profile To Use
  --token <value>                   Coalesce Refresh Token
  --databricksAuthType <value>      Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>      Databricks Client ID
  --databricksClientSecret <value>  Databricks Client Secret
  --databricksPath <value>          Databricks Path
  --databricksToken <value>         Databricks Token
  --snowflakeAuthType <value>       Snowflake Auth Type (Basic, KeyPair)
  --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)
  -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>​

Rerun a failed pipeline. This only works on failed refreshes, and only the nodes that previously failed will be run.

coa will return 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.
re-runs a failed Coalesce pipeline. Runtime parameters from the previous run will not be preserved.

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

Options:
  --domain <value>                  Coalesce domain name to use for API requests (default:
                                    "https://app.coalescesoftware.io")
  --environmentID <value>           Environment ID
  --exclude <value>                 Coalesce Node Selector
  --include <value>                 Coalesce Node Selector
  --jobID <value>                   Coalesce JobID
  --parallelism <value>             Parallelism level to use
  --parameters <value>              Parameters
  --platformKind <value>            Platform Kind (Snowflake, Databricks) (default: "Snowflake")
  --profile <value>                 Profile To Use
  --token <value>                   Coalesce Refresh Token
  --databricksAuthType <value>      Databricks Auth Type (OAuthM2M, Token)
  --databricksClientID <value>      Databricks Client ID
  --databricksClientSecret <value>  Databricks Client Secret
  --databricksPath <value>          Databricks Path
  --databricksToken <value>         Databricks Token
  --snowflakeAuthType <value>       Snowflake Auth Type (Basic, KeyPair)
  --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)
  -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]​

See information about your Environments.

Flags

coa environments -h

Environments

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

Commands:
  list [options]  List Environments
  get [options]   Get Environment
  help [command]  display help for command

$ coa nodes [options] [command]​

Returns information about the Nodes in the Environment added to your .config file.

Flags

coa nodes -h

Nodes

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

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

$ coa runs [options] [command]​

See information about your Runs.

Flags

coa runs -h

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 cancel [options] <runID>​

Cancel a running pipeline.

Flags

coa cancel -h

Arguments:
  runID                    The ID of the run to cancel.

Options:
  --environmentID <value>  Environment ID (default: "")
  -h, --help               display help for command

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

Create, update, and see information about Nodes in a specific workspace. For a list of available fields see:

Flags

coa workspace-nodes -h

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

Parallelism Limits​

The parallelism parameter determines how many nodes are processed simultaneously (in parallel) by the Snowflake compute warehouse. The API allows a maximum limit of 64, while coa is uncapped.

Overwriting Defaults​

You can overwrite the default coa file information by passing in the flags to the CLI or entering the information in the API request.

Using Include and Exclude​

Include and Exclude use the Selector format.

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 }'