<p align="center">
  <img src="https://raw.githubusercontent.com/gooddata/gooddata-ui-sdk/master/assets/gooddata-logo.svg" alt="GoodData Logo" width="120px" height="120px"/>
</p>
<h1 align="center">GoodData CLI</h1>

> GoodData for VS Code and GoodData CLI are available for you to try out and provide feedback. Avoid using them in a production environment.

Manage your analytics as code. The solution consists of two components:

* [GoodData Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=GoodData.gooddata-vscode).
* [GoodData Command-line Interface](https://www.npmjs.com/package/@gooddata/code-cli).

Together these tools allow you to:

1. Retrieve analytical objects from a GoodData server.
1. Create or update analytical objects in Visual Studio Code.
1. Preview analytical objects in Visual Studio Code.
1. Deploy analytical objects to a workspace.

The analytical objects you can work with include datasets, which form the logical data model, and metrics. Additionally, we have plans to incorporate support for visualizations in the near future.

With GoodData CLI you can:

* Initialize a new local environment.
* Clone an existing workspace.
* Validate local analytical objects.
* Deploy your analytical objects to a workspace.

## Prerequisites

Before getting started, ensure that you have:

* GoodData [workspace](https://www.gooddata.com/developers/cloud-native/doc/cloud/create-workspaces/concepts/workspace/).
* [API access token](https://www.gooddata.com/developers/cloud-native/doc/cloud/manage-organization/user-token/).
* [Node.js version 16.17 or newer installed](https://nodejs.org/).

## Install CLI

In terminal, run `npm i -g @gooddata/code-cli`.
You should have a new CLI command available, try running `gd -v` or `gd --help`.

## `gd init` command

Once the CLI is installed you are able to initialize your local environment.

**Steps:**

1. Open a terminal and navigate to a folder where you want to build and store your analytics.
1. To initialize your local environment, run `gd init` and follow the instructions to create a `gooddata.yaml` configuration file.

> The gd_init step also creates `.env` and  `.gitignore` files, in case you wish to store the analytics in a Version Control System (like Git)


## `gd clone` command

To clone existing workspace to your local environment, run `gd clone`.

You should now have an `analytics` folder that contains your analytical objects.

## `gd validate` command

GoodData CLI validate your local environment. This is useful if you want to set up CI/CD pipelines
and, for example, ensure the workspace is valid before merging a pull request.

GoodData CLI validates:
* syntax of the YAML files is correct.
* properties (e.g. there can' be any missing or invalid).
* references between analytical objects.
* references to the database tables and columns.

To execute validation, run `gd validate`.

## `gd deploy` command

GoodData CLI can deploy your local environment to a workspace defined in `gooddata.yaml` file.

To execute the deployment, run `gd deploy`.

Before deploying, GoodData CLI will also run validation, unless `--no-validate` argument was passed to the command.