# Training

## Overview

A introductory walk-through to `codestream-cli` using common command-line examples.

## Prepare

This walk-through is based on the assumption that all commands will be run inside a temporary container. There several options for running `codestream-cli`, and if you are running under different conditions you will need to adjust the commands accordingly.

---

⚠️ **NOTE:**

If you don't wish to run the container image interactively, another option is to use the container's default entrypoint (`codestream-cli`) directly.

However if you choose this path, you will need to ensure that all the required environment variables are available either by using an `env` file or passing the correct flags to the cli before starting.

---

### System Environment Variables

Set the following variables in your local shell. If you intend on using `codestream-cli` often, I suggest adding them to your personal `dotfiles` to avoid needing to do this each time.

```bash
# Container registry variables.
REGISTRY="ghcr.io"
IMAGE="salt-labs/containers/codestream-cli"
TAG="latest"
CONTAINER="${REGISTRY}/${IMAGE}:${TAG}"

# User variables
export CODESTREAM_CLI_VRA_URL="https://vmwareauto.saltlabs.cloud"
export CODESTREAM_CLI_VRA_USERNAME="put_username_here"

# Optional user variables if you want to increase logging.
export CODESTREAM_CLI_LOG_LEVEL="DEBUG"
export CODESTREAM_CLI_LOG_FILE="codestream-cli.log"

# A shortcut if you decide to use the entrypoint directly.
CODESTREAM_CLI_COMMAND="docker container run --name codestream-cli --rm --env-file .env ${CONTAINER}"
```

### Container

- If you haven't already, make sure you are logged into the registry before continuing.

```bash
docker login ${REGISTRY}
```

- Ensure you can pull the `codestream-cli` container image locally before continuing.

```bash
docker image pull ${CONTAINER}
```

#### Container Environment Variables

- In order to make the process repeatable for subsequent container launches, it is suggested that you create a reusable `env` file. This allows you to pass through your local environment variables you set previously into the container each launch time.

---

⚠️ NOTE: You have 2 options here depending on you're desired setup.

**Option 1.** You can set the values for the variables you desire directly in `.env` file with the format `VARIABLE=VALUE`. This file is then read by the docker command.

_If you only intend to run the container as a user, this is the recommended approach._

```bash
# Example that sets the values directly inside the .env file
cat <<-EOF > .env

CODESTREAM_CLI_LOG_LEVEL="INFO"
CODESTREAM_CLI_VRA_URL="https://vmwareauto.saltlabs.cloud"

EOF
```

**Option 2.** You can set the values for the variables in your local system's `dotfiles` and pass them through with the format `VARIABLE`.

_If you intend to run the container as a user but **also perform local development** of `codestream-cli` this is the recommended approach._

```bash
# Example setup of local dotfiles
cat <<- EOF >> ${HOME}/.bashrc

# codestream-cli
export CODESTREAM_CLI_LOG_LEVEL="INFO"
export CODESTREAM_CLI_VRA_URL="https://vmwareauto.saltlabs.cloud"

EOF

# Example that passes local values inside the container.
cat <<-EOF > .env

CODESTREAM_CLI_LOG_LEVEL
CODESTREAM_CLI_VRA_URL

EOF
```

You can mix and match depending on you're local system setup.

The below full example has already setup the variables in the local system `dotfiles` and passes the majority through from the local system into the container (this was option 2 above).

You will note the example of the log file location has been overridden to be accessible in the current directory inside the container.

---

```bash
cat <<-EOF > .env

# This defaults to INFO, but the following are valid. DEBUG, INFO, WARNING, ERROR
CODESTREAM_CLI_LOG_LEVEL

# If not set, will write all logs to stdout.
CODESTREAM_CLI_LOG_FILE=codestream-cli.log

# Set this to true for additional debug information.
CODESTREAM_CLI_TRACE_ENABLED

# Set to true to ignore certificate errors.
CODESTREAM_CLI_SKIP_VERIFY_CERTS

# Set this to the vRA URL if you don't want to have to do --url for all commands.
CODESTREAM_CLI_VRA_URL

# The credentials to login to vRA
CODESTREAM_CLI_VRA_USERNAME
CODESTREAM_CLI_VRA_PASSWORD

# If you already have a token, you can pass it into the container.
CODESTREAM_CLI_VRA_TOKEN

# A timeout in seconds to wait for the vRA API. Defaults to 3 if not defined.
CODESTREAM_CLI_VRA_TIMEOUT

EOF
```

- Start a temporary container image.

```bash
docker container run --rm --name codestream-cli -it --env-file .env --entrypoint /bin/bash "${CONTAINER}"
```

---

⚠️ NOTE: All commands from this point are to be run within the container environment unless otherwise specified.

---

## Examples

The following are common examples for working with `codestream-cli`. Additional subcommands can be found looking at the full documentation.

Each example is meant to act as a guide, showing you where to find the correct syntax from the in-built help.

_If you are lazy or get stuck, see the `Answer` sections included in each example._

### Tokens

To work with the vRA API, you first need to obtain a `refresh token`. This is a long-lived token that is then used to obtain short-lived `bearer` tokens dynamically with each command. These `bearer` token are required to work with the API.

#### Refresh Token

- Determine the correct command to obtain a `refresh token` by providing your vRA username and password.

```bash
# Show help
codestream-cli token --help

# Run you command here...

# TIP: If you're password contains special characters you will need to escape them or you can leave of the password input to be prompted to type it manually.

# Put your captured token into a variable for later use.
CODESTREAM_CLI_VRA_TOKEN="token_goes_here"
```

<details>
    <summary>Answer</summary>

```bash
CODESTREAM_CLI_VRA_TOKEN=$(\
codestream-cli \
    token \
        --refresh-token \
            --username ${CODESTREAM_CLI_VRA_USERNAME:-EMPTY} \
            --password ${CODESTREAM_CLI_VRA_PASSWORD:-EMPTY} \
)

# Confirm you have captured a valid looking token before continuing.
echo ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY}
```

</details>
<br />

#### Bearer Token

- This next example is not used very frequently (and is mostly only used for debugging auth issues). Figure out the command to obtain a `bearer` token using you're existing `refresh token`.

```bash
# Show help
codestream-cli token --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    token \
        --bearer-token
```

</details>
<br />

### Pipelines

#### Sample

- Write this simple Code Stream Pipeline sample to a file. This will be used for subsequent commands.

```bash
cat <<-EOF > codestream.yaml
---

kind: PIPELINE

project: P-Tristram-DEV
name: codestream-cli_test_${CODESTREAM_CLI_VRA_USERNAME:-unknown}
icon: lightbulb,down, is-warning
enabled: false
description: |-
  A dummy pipeline for testing codestream-cli.
concurrency: 1

input:
  deployment_name: codestream-cli_test_${CODESTREAM_CLI_VRA_USERNAME:-unknown}
  vra_url: https://vmwareauto.saltlabs.cloud

_inputMeta:
  deployment_name:
    description: The name of the deployment to check for.
    mandatory: true
  vra_url:
    description: The URL of the vRA instance.
    mandatory: true

workspace:
  type: DOCKER
  endpoint: ''
  image: ''
  registry: Artifactory
  path: ''
  autoCloneForTrigger: false
  limits:
    cpu: 1.0
    memory: 512

stageOrder:

  - check

stages:

  check:

    taskOrder:

      - get_token

    tasks:

      get_token:
        type: Pipeline
        input:
          pipeline: vra_get_token
          inputProperties:
            API_Token: \${var.vra_api_token}
            vra_url: \${input.vra_url}

EOF
```

#### Validate

- Determine the correct command to `validate` the pipeline file to check the syntax looks correct.

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
codestream-cli \
    pipelines \
        --validate-pipeline \
            --file codestream.yaml
```

</details>
<br />

#### Check (doesn't exist)

- Determine the correct command to `check` that an existing pipeline using that name doesn't already exist in vRA.

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --check-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

#### Import

- Determine the correct command to `import` the pipeline using the file created earlier.

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --import-pipeline \
            --file codestream.yaml
```

</details>
<br />

#### Check (exists)

- Determine the correct command to `check` that the pipeline now does exist in vRA

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --check-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

#### Update

- Make a change to the pipeline file and determine the correct command to `import` it again to update the pipeline.

```bash
# Show help
codestream-cli pipelines --help

# Example change to update the description.
sed -i "s/  A dummy pipeline for testing codestream-cli./  A dummy pipeline (now updated) for testing codestream-cli./g" codestream.yaml

# Run your command here...

# Verify the change in the UI
gio open ${CODESTREAM_CLI_VRA_URL:-EMPTY}
```

<details>
    <summary>Answer</summary>

```bash
codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --import-pipeline \
            --file codestream.yaml
```

</details>
<br />

#### Export (on-screen)

- Determine the correct command to `export` the pipeline on-screen

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --export-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

#### Export (to file)

- Determine the correct command to `export` the same pipeline to a file.

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --export-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY} \
            --file pipeline_export.yaml
```

</details>
<br />

#### Get Info

- Determine the correct command to `get information` about the existing pipeline in vRA.

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-info \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

#### Get Id

- Determine the correct command to obtain just the `id` for the existing pipeline in vRA.

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-id \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

- Get the `execution ids` for the existing pipeline (shouldn't be any yet)

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-executions \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

- Determine the correct command to `enable` the pipeline for executions

```bash
# Show help
codestream-cli pipelines --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --enable-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

- Determine the correct command to `execute` the pipeline.

```bash
# Show help
codestream-cli pipeline --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-} \
    pipelines \
        --execute-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}

# Here is an example if you wanted to provide additional inputs.
PIPELINE_INPUTS=$(cat <<EOF
{
    "deployment_name": "",
}
EOF
)
codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --execute-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY} \
            --inputs ${PIPELINE_INPUTS[@]}
```

</details>
<br />

- Determine the correct command to `get execution ids` for the existing pipeline (should work now)

```bash
# Show help
codestream-cli pipeline --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --get-pipeline-executions \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

- Determine the correct command to `delete` the pipeline

```bash
# Show help
codestream-cli pipeline --help

# Run your command here...
```

<details>
    <summary>Answer</summary>

```bash
PIPELINE_NAME=$(egrep "^name:" codestream.yaml | cut -d" " -f2)
PIPELINE_PROJECT=$(egrep "^project:" codestream.yaml | cut -d" " -f2)

# This example deletes the pipeline
codestream-cli  --url ${CODESTREAM_CLI_VRA_URL:-EMPTY} --token ${CODESTREAM_CLI_VRA_TOKEN:-EMPTY} \
    pipelines \
        --delete-pipeline \
            --name ${PIPELINE_NAME:-EMPTY} \
            --project ${PIPELINE_PROJECT:-EMPTY}
```

</details>
<br />

### Deployments

TODO: Complete this section when the subcommand is ready...

### Blueprints

TODO: Complete this section when the subcommand is ready...

### End

- Exit the container image when you have finished.

```bash
exit
```