# Tilores CLI

Tilores CLI is the tool to create and manage your Tilores project and instance.

## Installation

Tilores CLI requires `go` to be installed. Follow the official documentation if
you don't have `go` installed: https://golang.org/doc/install

Verify your `go` installation afterwards by running

```
go version
```

Afterwards, install and verify the Tilores CLI:

```
go install github.com/tilotech/tilores-cli@latest
tilores-cli version
```

!!!
For Mac OS make sure `$GOPATH` is set and the go binary path is added to `$PATH`. To do so run the following:
```
export GOPATH=~/go
export PATH=$PATH:$GOPATH/bin
```
To make this work for new terminal sessions it needs to be added to the dotfile e.g `~/.bashrc` or `~/.zshrc` etc.,
depending on which terminal you use.
!!!

## Commands

The following commands can be used with the Tilores CLI.

### deploy

Deploys an instance of Tilores into your own AWS account.

You can only deploy if you have a valid license and your AWS account has been
registered by our service team (service@tilotech.io).

You must have valid credentials for your AWS account configured either via
[environment variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)
or via a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
For security reasons, we do not offer flags for providing the credentials. If
you are using a credentials file, you can optionally specify a profile using the
`--profile` flag.

#### Example Usage

```
tilores-cli deploy --region eu-west-1
```

#### Flags

`--profile`: Specify the AWS profile to use.

`--region`: Specify the AWS region into which to deploy. Must be one of the
[official AWS region codes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions),
e.g. us-east-1 for North Virginia or eu-west-1 for Ireland.

`--workspace`: Specify the deployment workspace/environment to deploy. e.g. `production`, `development`

`--var-file`: Specify the variables file path. e.g. `prod.tfvars`, `dev.tfvars`.
In this example the file is placed in `deployment/tilores`

### destroy

Removes your instance of Tilores and all of its data from your AWS account.

!!!warning
Be careful when using this on a production account. The data cannot be restored
afterwards!
!!!

You must have valid AWS credentials configured to use this command.

#### Example Usage

```
tilores-cli destroy --region eu-west-1
```

#### Flags

`--profile`: Specify the AWS profile to use.

`--region`: Specify the AWS region in which your Tilores instance is deployed.

`--workspace`: Specify the deployment workspace/environment to destroy. e.g. `production`, `development`

`--var-file`: Specify the variables file path. e.g. `prod.tfvars`, `dev.tfvars`.
In this example the file is placed in `deployment/tilores`

### erase

Erases all data from the Tilores instance in your AWS account.
!!!
This process can take minutes or even hours depending on the amount of data to erase.
!!!

!!!warning 
Be careful when using this on a production account. The data cannot be restored
afterwards!
!!!

!!!warning
This process generates costs, for large amounts of data (more than 100,000 records) we recommend
redeploying (destroy then deploy) instead.
!!!

You must have valid AWS credentials configured to use this command.

#### Example Usage

```
tilores-cli erase --region eu-west-1
```

#### Flags

`--profile`: Specify the AWS profile to use.

`--region`: Specify the AWS region in which your Tilores instance is deployed.

`--workspace`: Specify the deployment workspace/environment to erase data from. e.g. `production`, `development`

### init

Initializes a new Tilores project with all the required files and dependencies.

#### Example Usage

```
tilores-cli init
```

or

```
tilores-cli init my-project-folder
```

#### Flags

`--deploy-prefix`: The initial prefix for resources created during the deploy
phase, defaults to a random eight character string and can be changed later in
the generated files.

`--module-path` or `-m`: The go module path for the generated `go.mod` file,
defaults to the project folder name. It is best practice in `go` to use your
repository path, e.g. `github.com/foocompany/fooproject`.

### plan

Plans what needs to be changed when [deploying](#deploy) an instance of Tilores
into your own AWS account.

You can only plan if you have a valid license and your AWS account has been
registered by our service team (service@tilotech.io).

You must have valid AWS credentials configured to use this command.

#### Example Usage

```
tilores-cli plan --region eu-west-1
```

#### Flags

`--profile`: Specify the AWS profile to use.

`--region`: Specify the AWS region into which to deploy. Must be one of the
[official AWS region codes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions),
e.g. us-east-1 for North Virginia or eu-west-1 for Ireland.

`--workspace`: Specify the deployment workspace/environment to deploy. e.g. `production`, `development`

`--var-file`: Specify the variables file path. e.g. `prod.tfvars`, `dev.tfvars`.
In this example the file is placed in `deployment/tilores`

### rules simulate

Simulates the rules in rule-config.json and tries to match the provided records.

Reads the rule configuration from `./rule-config.json` file.

Reads both records to match as json from standard input.

#### Example Usage

```shell
cat records.json | tilores-cli rules simulate
```

Where `records.json` contains the following:

```json
{
  "recordA": {
    "myCustomField": "same value"
  },
  "recordB": {
    "myCustomField": "same value"
  }
}
```

#### Flags

`--json` or `-j`: Shows output as JSON

### rules test

Tests the rules in rule-config.json and checks if results match the expectations.

Reads the rule configuration from `./rule-config.json` file.

Test cases are read from `./test/rules/*.json` where each file represents a test case and
includes a pair of records and an expectation.

Each expectation is a list of rule sets with their expected satisfied and unsatisfied rules.

#### Example Usage

```shell
tilores-cli rules test
```

Where `./test/rules/case1.json` contains the following:

```json
{
  "recordA": {
    "myCustomField": "same value"
  },
  "recordB": {
    "myCustomField": "same value"
  },
  "expectation": {
    "ruleSets": [
      {
        "ruleSetID": "index",
        "satisfiedRules": [
          "R1EXACT"
        ],
        "unsatisfiedRules": [
          "R2OTHER"
        ]
      }
    ]
  }
}
```

### upgrade

Upgrades Tilores to the latest version. If the upgrade encounters any files that
need to be updated, but were changed by the user, it will automatically create a
backup of the old file. It is highly recommended to compare the differences and
adjust the new file accordingly.

#### Example Usage

```
tilores-cli upgrade
```

### version

Prints the version information of the Tilores CLI.

#### Example Usage

```
tilores-cli version
```