### Start Minikube, Install ArgoCD + SKE, Deploy ConfigMap Promise

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

This bash script automates the entire setup process for SKE Cortex integration testing. It ensures minikube is running, installs ArgoCD and the SKE operator, configures GitOps, builds and loads a pipeline image, and deploys the ConfigMap Promise. It also includes checks for resource availability and provides post-setup instructions.

```bash
#!/usr/bin/env bash
set -euo pipefail

# 1. Start minikube if not running
if minikube status | grep -q "Running"; then
    echo "minikube already running"
else
    echo "Starting minikube..."
    minikube start --memory=8192 --cpus=4
fi

# 2. Create GitHub repo for GitOps (idempotent)
echo "Ensuring GitHub repo jeff-test-org/ske-test-resources exists..."
gh repo create jeff-test-org/ske-test-resources --public --clone=false 2>/dev/null || \
    echo "  Repo already exists."

# 3. Install ArgoCD
echo "Installing ArgoCD..."
kubectl create namespace argocd --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
echo "Waiting for ArgoCD to be ready..."
kubectl wait --for=condition=available deployment/argocd-server \
    -n argocd --timeout=300s

# 4. Apply ArgoCD Application to watch the GitOps repo
echo "Configuring ArgoCD Application..."
kubectl apply -f ske/argocd-app.yaml

# 5. Create GHCR image pull secret for Syntasso images
echo "Creating image pull secret for Syntasso GHCR..."
kubectl create namespace kratix-platform-system --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret docker-registry syntasso-registry \
    --namespace=kratix-platform-system \
    --docker-server=ghcr.io \
    --docker-username=syntasso-pkg \
    --docker-password="${SKE_LICENSE_TOKEN}" \
    --dry-run=client -o yaml | kubectl apply -f -

# 6. Install SKE Operator via Helm
echo "Installing SKE Operator..."
helm repo add syntasso https://syntasso.github.io/helm-charts 2>/dev/null || true
helm repo update syntasso
helm upgrade --install ske-operator syntasso/ske-operator \
    --namespace kratix-platform-system \
    --create-namespace --wait \
    --values ske/values.yaml \
    --set skeLicense="${SKE_LICENSE_TOKEN}" \
    --set skeDeployment.version="${SKE_VERSION}" \
    --set cortexIntegration.config.token="${CORTEX_API_KEY}" \
    --set cortexIntegration.config.url="${CORTEX_BASE_URL}"

# 7. Wait for Kratix pods to be ready
echo "Waiting for Kratix platform pods..."
kubectl wait --for=condition=available deployment --all \
    -n kratix-platform-system --timeout=300s

# 8. Build and load pipeline image into minikube
echo "Building pipeline image..."
docker build -t ske-test/message-pipeline:v0.1.0 \
    ske/workflows/resource/configure/message-configure/ske-test-message-pipeline
echo "Loading pipeline image into minikube..."
minikube image load ske-test/message-pipeline:v0.1.0

# 9. Install the ConfigMap Promise
echo "Installing ConfigMap Promise..."
kubectl apply -f ske/promise.yaml

# 10. Wait for Promise to become Available
echo "Waiting for Promise to become Available..."
for i in $(seq 1 60); do
    STATUS=$(kubectl get promise message -o jsonpath='{.status.conditions[?(@.type=="Available")].status}' 2>/dev/null || echo "")
    if [ "$STATUS" = "True" ]; then
        echo "Promise is Available!"
        break
    fi
    if [ "$i" -eq 60 ]; then
        echo "Warning: Promise did not become Available within 120s"
        kubectl get promise message -o yaml
        exit 1
    fi
    sleep 2
done

echo ""
echo "SKE setup complete."
echo "  - Kratix:  kubectl get pods -n kratix-platform-system"
echo "  - Promise: kubectl get promise message"
echo "  - ArgoCD:  kubectl port-forward svc/argocd-server -n argocd 8080:443"
echo ""
echo "Run 'just ske-test' to verify the Cortex integration."

```

--------------------------------

### Set Up SKE + Cortex Integration Test

Source: https://github.com/cortexapps/cli/blob/main/internal/README.md

Starts minikube, installs necessary components like ArgoCD, cert-manager, and SKE, then deploys a Promise object for integration testing.

```bash
just ske-setup
```

--------------------------------

### Example .env File Setup for Cortex CLI Tests

Source: https://github.com/cortexapps/cli/blob/main/internal/tests/README.md

Sets up environment variables required for Cortex CLI functional tests. Ensure sensitive information like API keys and tokens are not committed to version control.

```bash
export CORTEX_API_KEY=your-cortex-api-key
export CORTEX_BASE_URL=https://api.getcortexapp.com
export GITHUB_TEST_ORG=my-cortex-test-org
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
export GITHUB_TEST_USERNAME=some-github-user
export GITHUB_INTEGRATION_ALIAS=your-github-integration-alias
```

--------------------------------

### Install Dependencies and Set Up Environment

Source: https://github.com/cortexapps/cli/blob/main/internal/README.md

Clone the repository, install Python dependencies using Poetry, and set up the local environment by copying and editing the .env.example file.

```bash
git clone git@github.com:cortexapps/cli.git
cd cli
poetry install
cd internal
cp .env.example .env
# Edit .env and fill in your API keys and tokens (see comments in the file)
```

--------------------------------

### Install Cortexapps CLI using Homebrew

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Install the CLI using Homebrew by tapping the Cortexapps repository and then installing the package.

```bash
brew tap cortexapps/tap
brew install cortexapps-cli
```

--------------------------------

### Install Cortex CLI

Source: https://context7.com/cortexapps/cli/llms.txt

Install the Cortex CLI using pip, Homebrew, or Docker. Ensure you have an API key for configuration.

```bash
pip install cortexapps-cli
```

```bash
brew tap cortexapps/tap && brew install cortexapps-cli
```

```bash
docker run -e CORTEX_API_KEY=<key> cortexapp/cli <args>
```

--------------------------------

### Install Dependencies and Set Environment Variables

Source: https://github.com/cortexapps/cli/blob/main/CLAUDE.md

Install project dependencies using Poetry and set necessary environment variables for testing the Cortex CLI. Ensure you replace placeholders with your actual API keys and URL.

```bash
# Install dependencies
poetry install

# Set required environment variables for testing
export CORTEX_API_KEY=<your-api-key>
export CORTEX_BASE_URL=https://api.getcortexapp.com  # optional, defaults to this
export CORTEX_API_KEY_VIEWER=<viewer-api-key>  # for viewer permission tests
```

--------------------------------

### Validate Environment Variables at Startup

Source: https://github.com/cortexapps/cli/blob/main/internal/axon/relay-improvements.md

This example shows how to provide a clear error message when required environment variables for an integration are missing.

```text
Error: Integration "jira" requires JIRA_USERNAME and JIRA_TOKEN.
  JIRA_API:      https://jeff-schnitter-proton.atlassian.net (set)
  JIRA_USERNAME: (not set)  <-- MISSING
  JIRA_TOKEN:    (set)

See: https://docs.cortex.io/axon-relay/configuration
```

--------------------------------

### Install GitHub CLI on macOS

Source: https://github.com/cortexapps/cli/blob/main/internal/tests/README.md

Installs the GitHub CLI using Homebrew on macOS. Verify the installation by checking the version.

```bash
# macOS
brew install gh
```

```bash
# Verify
gh --version
```

--------------------------------

### Install Cortexapps CLI using pip

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Install the CLI using pip. It is recommended to use a Python virtual environment.

```bash
pip install cortexapps-cli
```

```bash
VENV_DIR=~/.venv/cortex
python3 -m venv $VENV_DIR
source $VENV_DIR/bin/activate
pip install cortexapps-cli
```

--------------------------------

### Verify Cortex CLI Installation

Source: https://context7.com/cortexapps/cli/llms.txt

Verify the installation by checking the CLI version. You can also select a non-default tenant for commands.

```bash
cortex version
# Output: 1.15.0
```

```bash
cortex -t staging catalog list
```

--------------------------------

### Run All Tests with Just

Source: https://github.com/cortexapps/cli/blob/main/DEVELOPER.md

Execute all project tests using the 'just test-all' command. Ensure 'just' is installed.

```bash
just test-all
```

--------------------------------

### Start Axon Relay Containers

Source: https://github.com/cortexapps/cli/blob/main/internal/README.md

Starts the Docker containers for the Axon relay, enabling communication with configured integrations.

```bash
just axon-setup
```

--------------------------------

### Set Up Echo Server and Axon Relay for Smoke Test

Source: https://github.com/cortexapps/cli/blob/main/internal/README.md

Starts the echo server and Axon relay for smoke testing.

```bash
just axon-echo-setup
```

--------------------------------

### List entities in a specific tenant

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Example command to list all entities in the 'my-test' tenant using the CLI.

```bash
cortex -t my-test catalog list
```

--------------------------------

### Set Up K8s Agent Integration Test

Source: https://github.com/cortexapps/cli/blob/main/internal/README.md

This command starts minikube, deploys the k8s agent, and sets up test objects for integration testing.

```bash
just k8s-agent-setup
```

--------------------------------

### SKE Setup and Operations

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Commands for setting up, testing, and tearing down the SKE (Syntasso Kratix Enterprise) environment, including Minikube, ArgoCD, and Promise deployment.

```bash
just ske-setup                # start minikube, install ArgoCD + SKE, deploy Promise
```

```bash
just ske-test                 # verify end-to-end: Cortex Entity Type → Git → K8s
```

```bash
just ske-stop                 # tear down everything + stop minikube
```

--------------------------------

### SKE Promise Example Resource

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Example YAML for a Kubernetes resource request, specifically a 'Message' Kind within the 'demo.cortex.io' group, used in SKE integration.

```yaml
apiVersion: demo.cortex.io/v1alpha1
kind: Message
metadata:
  name: example-message
  namespace: default
spec:
  # Add your message spec here
```

--------------------------------

### Update Example Resource for SKE Integration

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

Replace the default `example-resource.yaml` with this content to define a Message resource with a specific message payload for testing.

```yaml
apiVersion: demo.cortex.io/v1alpha1
kind: Message
metadata:
  name: example-message
  namespace: default
spec:
  message: "hello from ske"
```

--------------------------------

### K8s Agent Setup and Operations

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Commands for setting up, testing, and tearing down the K8s agent environment, including Minikube and test objects.

```bash
just k8s-agent-setup          # start minikube, deploy k8s-agent + test objects
```

```bash
just k8s-agent-test           # verify test objects appear in Cortex
```

```bash
just k8s-agent-stop           # tear down + stop minikube
```

--------------------------------

### Install SKE Operator with Cortex Integration

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

Install the SKE operator using Helm, configuring Cortex integration with API keys and URLs. Ensure the SKE license token is set.

```bash
# helm install ske-operator syntasso/ske-operator \
#   --namespace kratix-platform-system \
#   --create-namespace --wait \
#   --values ske/values.yaml \
#   --set skeLicense=${SKE_LICENSE_TOKEN} \
#   --set cortexIntegration.config.token=${CORTEX_API_KEY} \
#   --set cortexIntegration.config.url=${CORTEX_BASE_URL}
```

--------------------------------

### Axon Relay Setup and Operations

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Commands for setting up and testing the Axon relay, including a simple echo server smoke test.

```bash
just axon-setup               # start relay containers for configured integrations
```

```bash
just axon-test                # set up Jenkins + relay end-to-end
```

```bash
just axon-echo-setup          # simple echo server relay smoke test
```

--------------------------------

### Apply with Server-Side Apply

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Use server-side apply for ArgoCD CRD installation when annotations exceed the client-side limit.

```bash
kubectl apply --server-side
```

--------------------------------

### Export and Import tenant data

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Example of exporting data from one tenant ('myTenant-dev') and importing it into another ('myTenant'). Requires API keys for both tenants in the config file.

```bash
cortex -t myTenant-dev backup export
```

```bash
cortex -t myTenant backup import -d <directory created by export>
```

--------------------------------

### List and Manage Initiatives

Source: https://context7.com/cortexapps/cli/llms.txt

Commands for listing, creating, getting, updating, and deleting initiatives. Use --include-drafts and --include-expired flags to modify list behavior. Creation requires a JSON file.

```bash
cortex initiatives list
```

```bash
cortex initiatives list --include-drafts --include-expired --table
```

```bash
cat > initiative.json <<EOF
{
  "name": "Security Hardening Q1",
  "description": "Improve security scorecard scores to Gold by end of Q1",
  "scorecardTag": "security-scorecard",
  "targetDate": "2025-03-31",
  "targetLevel": "GOLD"
}
EOF
cortex initiatives create -f initiative.json
```

```bash
cortex initiatives get --cid <cid>
```

```bash
cortex initiatives update --cid <cid> -f updated-initiative.json
```

```bash
cortex initiatives delete --cid <cid>
```

--------------------------------

### List Catalog Entries with Ownership Info

Source: https://github.com/cortexapps/cli/blob/main/STYLE.md

Example of listing catalog entries of a specific type and including ownership details. Use flags to filter and expand output.

```bash
cortex catalog list --include-owners --types service
```

--------------------------------

### Add Link to Team Resource

Source: https://github.com/cortexapps/cli/blob/main/STYLE.md

Example of adding a link to an existing team resource. Specify the URL, type, and name for the link.

```bash
cortex teams add link --url https://www.catster.com --type documentation --name Catster
```

--------------------------------

### Warn About Unsupported Auth Block

Source: https://github.com/cortexapps/cli/blob/main/internal/axon/relay-improvements.md

This example shows a warning message to display when the 'auth' block is used in a custom accept.json file, as it is not supported.

```text
Warning: "auth" block in accept.json is not supported for custom relays.
Use "headers" block instead. See: https://docs.cortex.io/axon-relay/custom-relays
```

--------------------------------

### Set Cortex API Key using Environment Variable

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Example of setting the Cortex API key using an environment variable. This overrides the config file.

```bash
export CORTEX_API_KEY=<YOUR_API_KEY>
```

--------------------------------

### Axon Relay Reproduction Steps

Source: https://github.com/cortexapps/cli/blob/main/internal/axon/jenkins/jenkins-bug.md

This bash script outlines the steps to reproduce the Axon relay `auth` block bug. It includes starting the Jenkins relay, triggering a workflow, and monitoring the relay logs.

```bash
# Start Jenkins + relay
just axon-test

# Trigger workflow
curl -s -H "Authorization: Bearer $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "${CORTEX_BASE_URL}/api/v1/workflows/jenkins-axon-relay/runs" \
  -d '{"scope": {"type": "GLOBAL"}}'

# Check relay logs
docker compose -f axon/compose.yaml logs -f jenkins-relay
```

--------------------------------

### Run Cortex CLI Locally

Source: https://github.com/cortexapps/cli/blob/main/CLAUDE.md

Execute the Cortex CLI commands locally using Poetry. Examples show listing catalog entities with and without specifying a tenant.

```bash
# Run the CLI locally
poetry run cortex <command>

# Examples:
poetry run cortex catalog list
poetry run cortex -t my-tenant catalog list
```

--------------------------------

### cortex workflows list-runs

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/specs/2026-04-06-github-workflow-action-block-tests-design.md

Lists workflow runs using GET /api/v1/workflows/runs. Supports filtering by workflow tag, entity, and start time, along with standard list command options.

```APIDOC
## cortex workflows list-runs

### Description
Lists runs via `GET /api/v1/workflows/runs`.

### Method
GET

### Endpoint
`/api/v1/workflows/runs`

### Parameters
#### Command Line Options
- **-t, --tag** (TEXT) - Optional - Filter by workflow tag(s) (multiple allowed)
- **-e, --entity** (TEXT) - Optional - Filter by entity tag
- **--started-after** (TEXT) - Optional - ISO datetime filter
- **--started-before** (TEXT) - Optional - ISO datetime filter
- (plus standard ListCommandOptions: --table, --csv, --columns, --filter, --sort, --page, --page-size)
```

--------------------------------

### Get Git Details for a Service

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Retrieves the Git repository details for a specified service using the `cortex catalog details` command and formats the output with `jq`.

```bash
cortex catalog details -t my-service-1 | jq ".git"
```

```json
{
  "repository": "my-org/my-service-1",
  "alias": null,
  "basepath": null,
  "provider": "github"
}
```

--------------------------------

### Run ske-setup

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

Execute the ske-setup command within the internal directory. Watch for common issues like GHCR auth failures, Helm chart not found, pod image pull errors, or unavailable Promises.

```bash
cd internal && just ske-setup
```

--------------------------------

### Add SKE Environment Variables to .env.example

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

Append these SKE-specific variables to your .env.example file. Ensure the SKE_LICENSE_TOKEN is a GitHub PAT.

```bash
# ---------------------------------------------------------------------------
# SKE (Syntasso Kratix Enterprise)
# ---------------------------------------------------------------------------

# Syntasso license token. This ghp_-prefixed GitHub PAT is used for both
# the SKE license and pulling images from ghcr.io/syntasso.
SKE_LICENSE_TOKEN=

# SKE version to install (e.g., v0.99.0). Check Syntasso docs for latest.
SKE_VERSION=v0.99.0
```

--------------------------------

### Check ArgoCD Sync Status

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Get the sync status of the `kratix-cortex-resources` application in the `argocd` namespace.

```bash
# Check ArgoCD sync status
kubectl get application kratix-cortex-resources -n argocd
```

--------------------------------

### Verify Justfile Syntax

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

This command checks if the 'ske-setup' recipe is present in the Justfile. It navigates to the 'internal' directory and lists all available Justfile recipes, filtering for those containing 'ske'.

```bash
cd internal && just --list | grep ske
```

--------------------------------

### Create Directory Structure

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

Use this command to create the necessary directory for SKE.

```bash
mkdir -p internal/ske
```

--------------------------------

### Check Kratix Components Running

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Verify that all Kratix components are running in the `kratix-platform-system` namespace.

```bash
# Check all Kratix components are running
kubectl get pods -n kratix-platform-system
```

--------------------------------

### Initiatives Management

Source: https://context7.com/cortexapps/cli/llms.txt

Commands for managing Cortex initiatives, including listing, creating, getting, updating, and deleting.

```APIDOC
## Initiatives Management

### List all active initiatives
```bash
cortex initiatives list
```

### Include drafts and expired initiatives
```bash
cortex initiatives list --include-drafts --include-expired --table
```

### Create an initiative from JSON
```bash
cat > initiative.json <<EOF
{
  "name": "Security Hardening Q1",
  "description": "Improve security scorecard scores to Gold by end of Q1",
  "scorecardTag": "security-scorecard",
  "targetDate": "2025-03-31",
  "targetLevel": "GOLD"
}
EOF
cortex initiatives create -f initiative.json
```

### Get initiative by CID
```bash
cortex initiatives get --cid <cid>
```

### Update initiative
```bash
cortex initiatives update --cid <cid> -f updated-initiative.json
```

### Delete initiative
```bash
cortex initiatives delete --cid <cid>
```
```

--------------------------------

### Get Specific Custom Data Key

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieves the value of a specific custom metadata key for an entity.

```bash
# Get a specific key
cortex custom-data get --tag my-service --key ci-cd-tool
```

--------------------------------

### Get scorecard scores for a catalog entity

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieves all scorecard scores evaluated for a specific catalog entity.

```bash
cortex catalog scorecard-scores --tag my-service
```

--------------------------------

### Get Single Workflow as YAML

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieves the definition of a specific workflow in YAML format. Useful for inspection or backup.

```bash
# Get a single workflow as YAML
cortex workflows get --tag my-workflow --yaml
```

--------------------------------

### Create Team from File

Source: https://github.com/cortexapps/cli/blob/main/STYLE.md

Demonstrates creating a team resource using a JSON or YAML file. The `--file` flag specifies the input definition.

```bash
cortex teams create --file input.json
```

--------------------------------

### Scaffolding a Promise with Kratix CLI

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/specs/2026-04-23-ske-cortex-integration-test-design.md

Use the Kratix CLI to initialize a new Promise, define its API, and add a container for the resource configuration pipeline. The pipeline image must be built locally and loaded into minikube.

```bash
kratix init promise message --group demo.cortex.io --kind Message
kratix update api --property message:string
kratix add container resource/configure/message-configure \
  --image ske-test/message-pipeline:v0.1.0 --language python
```

--------------------------------

### Get GitOps log for a catalog entity

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieves the most recent GitOps processing log for a specified catalog entity.

```bash
cortex catalog gitops-log --tag my-service
```

--------------------------------

### Safe Team Deletion

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-07-gh-workflow-tests-minimal-slice.md

Deletes a GitHub team only if its slug starts with the predefined RESOURCE_PREFIX. Uses the gh_api helper function.

```python
def safe_delete_team(org, team_slug):
    """Delete a GitHub team, but only if the slug matches the safety prefix."""
    if not team_slug.startswith(RESOURCE_PREFIX):
        raise RuntimeError(
            f"Refusing to delete team '{team_slug}' — "
            f"name does not start with '{RESOURCE_PREFIX}'"
        )
    gh_api("DELETE", f"/orgs/{org}/teams/{team_slug}")
```

--------------------------------

### Safe Repository Deletion

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-07-gh-workflow-tests-minimal-slice.md

Deletes a GitHub repository only if its name starts with the predefined RESOURCE_PREFIX. Requires GITHUB_TEST_PAT environment variable.

```python
def safe_delete_repo(repo_full_name):
    """Delete a GitHub repo, but only if the name matches the safety prefix."""
    # repo_full_name is "org/repo-name"
    repo_name = repo_full_name.split("/")[-1]
    if not repo_name.startswith(RESOURCE_PREFIX):
        raise RuntimeError(
            f"Refusing to delete repo '{repo_full_name}' — "
            f"name does not start with '{RESOURCE_PREFIX}'"
        )
    pat = get_env("GITHUB_TEST_PAT")
    env = {**os.environ, "GH_TOKEN": pat}
    subprocess.run(
        ["gh", "repo", "delete", repo_full_name, "--yes"],
        capture_output=True,
        text=True,
        env=env,
    )
```

--------------------------------

### List Available Just Recipes

Source: https://github.com/cortexapps/cli/blob/main/DEVELOPER.md

View all available automation commands (recipes) by running 'just'. This helps in understanding the project's testing and development workflows.

```bash
$ just
Available recipes:
    help
    test testname # Run a single test, ie: just test tests/test_catalog.py
    test-all      # Run all tests
    test-import   # Run import test, a pre-requisite for any tests that rely on test data.
```

--------------------------------

### Get Workflow Run Status

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieves the status and output of a specific workflow run using its tag and run ID.

```bash
cortex workflows get-run --tag my-workflow --run-id run-abc123
# Output:
# { "id": "run-abc123", "status": "COMPLETED", "output": { ... } }
```

--------------------------------

### List Available Just Recipes

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

View all available automation scripts (recipes) defined in the Justfile within the internal directory.

```bash
just
```

--------------------------------

### workflows list / workflows get / workflows create

Source: https://context7.com/cortexapps/cli/llms.txt

Workflow management. Manage Cortex workflows (automation flows for runbooks and operations).

```APIDOC
## `workflows list` / `workflows get` / `workflows create` — Workflow management

Manage Cortex workflows (automation flows for runbooks and operations).

```bash
# List all workflows
cortex workflows list

# List with actions included
cortex workflows list --include-actions

# Search by name/description
cortex workflows list --search-query "github"

# Get a single workflow as YAML
cortex workflows get --tag my-workflow --yaml

# Create or update from YAML file
cat > my-workflow.yaml <<EOF
tag: deploy-notification
name: Deploy Notification
description: Sends Slack notification on deploy
trigger:
  type: DEPLOY
actions:
  - type: SLACK_MESSAGE
    channel: "#deployments"
    message: "{{entity.name}} deployed to {{deploy.environment}}"
EOF
cortex workflows create -f my-workflow.yaml
```
```

--------------------------------

### custom-data add / custom-data get / custom-data list

Source: https://context7.com/cortexapps/cli/llms.txt

Entity custom metadata. Manage arbitrary key-value metadata on catalog entities.

```APIDOC
## `custom-data add` / `custom-data get` / `custom-data list` — Entity custom metadata

Manage arbitrary key-value metadata on catalog entities.

```bash
# Add a single key-value pair
cortex custom-data add \
  --tag my-service \
  --key ci-cd-tool \
  --value Jenkins \
  --description "CI/CD tool used by this service"

# Add from a JSON file (supports nested values)
cat > custom-data.json <<EOF
{
  "description": "Build metrics",
  "key": "build-metrics",
  "value": {
    "2024-01-01": { "success-rate": "95" },
    "2024-01-02": { "success-rate": "98" }
  }
}
EOF
cortex custom-data add --tag my-service -f custom-data.json

# Bulk update multiple entities at once
cat > bulk-update.json <<EOF
[
  { "entityTag": "my-service-1", "key": "tier", "value": "1" },
  { "entityTag": "my-service-2", "key": "tier", "value": "2" }
]
EOF
cortex custom-data bulk -f bulk-update.json

# Get a specific key
cortex custom-data get --tag my-service --key ci-cd-tool

# List all custom data for an entity
cortex custom-data list --tag my-service --table

# Delete a key
cortex custom-data delete --tag my-service --key old-key
```
```

--------------------------------

### scorecards next-steps

Source: https://context7.com/cortexapps/cli/llms.txt

Get next steps for an entity in a scorecard. Returns the recommended next improvement actions for a specific entity in a scorecard.

```APIDOC
## `scorecards next-steps` — Get next steps for an entity in a scorecard

Returns the recommended next improvement actions for a specific entity in a scorecard.

```bash
cortex scorecards next-steps \
  --scorecard-tag production-readiness \
  --tag-or-id my-service
```
```

--------------------------------

### Get Catalog Entity OpenAPI Descriptor

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieve the OpenAPI/YAML descriptor for a catalog entity. The descriptor can be output in YAML or JSON format.

```bash
# Get YAML descriptor
cortex catalog descriptor --tag my-service --yaml
```

```bash
# Get JSON descriptor
cortex catalog descriptor -t my-service
```

```bash
# Pipe YAML descriptor through yq to modify and update
cortex catalog descriptor -y -t my-service \
  | yq '.info.x-cortex-groups += ["my-new-group"]' \
  | cortex catalog create -f-
```

--------------------------------

### Get Default Branch SHA

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-07-gh-workflow-tests-minimal-slice.md

Retrieves the SHA of the HEAD commit on the default branch (assumed to be 'main') of a given GitHub repository.

```python
def get_default_branch_sha(repo_full_name):
    """Get the SHA of the HEAD commit on the default branch."""
    result = gh_api("GET", f"/repos/{repo_full_name}/commits/main")
    return result["sha"]
```

--------------------------------

### Check GitOps Repo Contents

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

List all files and directories recursively within the `main` branch of the `jeff-test-org/ske-test-resources` GitHub repository.

```bash
# Check what's in the GitOps repo
gh api repos/jeff-test-org/ske-test-resources/git/trees/main?recursive=1 --jq '.tree[].path'
```

--------------------------------

### Record Deployment Event (JSON File)

Source: https://context7.com/cortexapps/cli/llms.txt

Records a deployment event by providing a JSON file as input. This is useful for complex deployment details or automation.

```bash
# Add from a JSON file
cat > deploy.json <<EOF
{
  "environment": "production",
  "sha": "abc123def456",
  "title": "Release v2.1.0",
  "type": "DEPLOY",
  "timestamp": "2024-01-15T14:30:00Z",
  "deployer": { "email": "deployer@example.com", "name": "Jane Smith" },
  "customData": { "jira_ticket": "ENG-1234" }
}
EOF
cortex deploys add --tag my-service -f deploy.json
```

--------------------------------

### Commit Justfile Changes

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

This command stages the modified Justfile and commits it with a descriptive message indicating the addition of the 'ske-setup' recipe.

```bash
git add internal/Justfile
git commit -m "feat: add ske-setup Justfile recipe"
```

--------------------------------

### Manage API Keys

Source: https://context7.com/cortexapps/cli/llms.txt

Commands for listing, creating, updating, and deleting API keys. Keys can be created with default or custom roles, or from a JSON file. Specify name, description, roles, and expiration date during creation.

```bash
cortex api-keys list --table
```

```bash
cortex api-keys create \
  --name "CI Pipeline Key" \
  --description "Used by GitHub Actions" \
  --default-roles USER \
  --expiration-date "2026-01-01"
```

```bash
cortex api-keys create --name "Deploy Bot" --custom-roles deploy-bot-role
```

```bash
cat > key.json <<EOF
{
  "name": "Automation Key",
  "roles": [{ "role": "READ_ONLY", "type": "DEFAULT" }],
  "description": "Read-only automation key"
}
EOF
cortex api-keys create -f key.json
```

```bash
cortex api-keys update --cid <cid> --name "Updated Name"
```

```bash
cortex api-keys delete --cid <cid>
```

--------------------------------

### Configure Local .env for SKE

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

Add these variables to your local .env file, replacing placeholders with your actual token and desired version.

```bash
# Add to internal/.env (not committed):
SKE_LICENSE_TOKEN=<your-token>
SKE_VERSION=v0.99.0
```

--------------------------------

### Record Deployment Event (Flags)

Source: https://context7.com/cortexapps/cli/llms.txt

Records a deployment event using command-line flags. Ensure all required fields like tag, type, and environment are provided.

```bash
# Add a deploy via flags
cortex deploys add \
  --tag my-service \
  --type DEPLOY \
  --environment production \
  --sha abc123def456 \
  --title "Release v2.1.0" \
  --email deployer@example.com \
  --name "Jane Smith" \
  --timestamp "2024-01-15T14:30:00" \
  --url "https://github.com/my-org/my-service/releases/tag/v2.1.0"
```

--------------------------------

### Get scorecard scores for all entities

Source: https://context7.com/cortexapps/cli/llms.txt

Returns evaluation scores for every entity tracked by a scorecard. Supports filtering by entity and exporting to CSV.

```bash
# Get all scores for a scorecard
cortex scorecards scores --scorecard-tag production-readiness
```

```bash
# Get scores for a specific entity
cortex scorecards scores -s production-readiness --tag-or-id my-service
```

```bash
# Export to CSV for comparison (using jq)
cortex scorecards scores -t myScorecard \
  | jq -r '.serviceScores[] | [.service.tag, .score.ladderLevels[].level.name // "noLevel", .score.summary.score|tostring] | join(",")' \
  | sort > /tmp/scores.csv
```

--------------------------------

### List SKE Test Recipe

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

This command lists available recipes in the Justfile, specifically checking for the 'ske-test' recipe. It's used to confirm the recipe's existence before execution.

```bash
cd internal && just --list | grep ske-test
```

--------------------------------

### Create Backup of All Scorecards

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Creates a backup of all scorecards by iterating through the list of scorecards, echoing the tag being backed up, and saving each scorecard's descriptor to a YAML file named after its tag.

```bash
for tag in `cortex scorecards list --csv -C tag`
   do
      echo "backing up: ${tag}"
      cortex scorecards descriptor -t ${tag} > ${tag}.yaml
done
```

--------------------------------

### Get scorecard definition or details

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieves a scorecard's full JSON details or its YAML descriptor. The descriptor can be useful for backups or editing.

```bash
# Get scorecard JSON details
cortex scorecards get --scorecard-tag production-readiness
```

```bash
# Get YAML descriptor (useful for backup/editing)
cortex scorecards descriptor --scorecard-tag production-readiness
cortex scorecards descriptor -t production-readiness > production-readiness.yaml
```

--------------------------------

### Get Catalog Entity Details

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieve full details for a single catalog entity using its x-cortex-tag. Details can be output as JSON or a table.

```bash
# Get JSON details for a service
cortex catalog details --tag my-service
```

```bash
# Extract git info using jq
cortex catalog details -t my-service | jq ".git"
# Output:
# {
#   "repository": "my-org/my-service",
#   "alias": null,
#   "basepath": null,
#   "provider": "github"
# }
```

```bash
# Get details as a table
cortex catalog details -t my-service --table
```

--------------------------------

### List all scorecards in the tenant

Source: https://context7.com/cortexapps/cli/llms.txt

Lists all scorecards, with options to include drafts or format output as CSV.

```bash
# List all published scorecards
cortex scorecards list
```

```bash
# Include draft scorecards
cortex scorecards list --show-drafts
```

```bash
# Output as CSV with tag and name columns
cortex scorecards list --csv --columns "Name=name" --columns "Tag=tag"
```

```bash
# Iterate over scorecard tags
for tag in $(cortex scorecards list --csv -C tag); do
  echo "Scorecard: $tag"
done
```

--------------------------------

### Verify GitHub Integration Alias

Source: https://github.com/cortexapps/cli/blob/main/internal/README.md

Use this command to retrieve all Cortex integrations and filter for the GitHub integration, verifying its alias. Requires jq to be installed.

```bash
poetry run cortex integrations get-all | jq '.configurations[] | select(.type == "github")'
```

--------------------------------

### Manage Cortex Teams

Source: https://context7.com/cortexapps/cli/llms.txt

Commands for creating, listing, getting, updating, archiving, unarchiving, and deleting Cortex teams. Supports both Cortex-managed and IDP-synced teams.

```bash
# Create a Cortex-managed team
cortex teams create \
  --tag platform-team \
  --name "Platform Team" \
  --description "Owns the infrastructure platform" \
  --type CORTEX
```

```bash
# Create an IDP-synced team
cortex teams create \
  --tag eng-team \
  --name "Engineering" \
  --type IDP \
  --idp-group "engineering" \
  --idp-provider "OKTA"
```

```bash
# Create from JSON file
cat > team.json <<EOF
{
  "type": "CORTEX",
  "teamTag": "my-team",
  "metadata": { "name": "My Team", "description": "A great team" },
  "cortexTeam": { "members": [{ "name": "Alice", "email": "alice@example.com" }] }
}
EOF
cortex teams create -f team.json
```

```bash
# List teams as table
cortex teams list --table
```

```bash
# Get a specific team
cortex teams get --team-tag platform-team
```

```bash
# Update team metadata
cortex teams update --team-tag platform-team --name "Platform Engineering"
```

```bash
# Archive / unarchive / delete
cortex teams archive  --team-tag old-team
cortex teams unarchive --team-tag old-team
cortex teams delete   --team-tag old-team
```

--------------------------------

### Set Up Jenkins and Axon Relay for End-to-End Test

Source: https://github.com/cortexapps/cli/blob/main/internal/README.md

Configures Jenkins and the Axon relay to prepare for an end-to-end workflow test.

```bash
just axon-test
```

--------------------------------

### Run Project Tasks with Just

Source: https://github.com/cortexapps/cli/blob/main/CLAUDE.md

Automate common development tasks using the 'just' command runner. This includes running all tests, importing test data, and executing specific test files.

```bash
# Run all available recipes
just

# Run all tests (requires prior test-import)
just test-all

# Run import test (prerequisite for other tests - loads test data)
just test-import

# Run a single test file
just test tests/test_catalog.py
```

--------------------------------

### Export All Workflows

Source: https://github.com/cortexapps/cli/blob/main/README.rst

This script exports all existing workflows as individual YAML files. This is useful for enabling GitOps for workflows or as a starting point for new workflow configurations.

```bash
for workflow in `cortex workflows list --csv --no-headers --columns tag`
do
   echo "workflow = $workflow"
   cortex workflows get --tag $workflow --yaml > $workflow.yaml
done
```

--------------------------------

### Check Current Version Tag

Source: https://github.com/cortexapps/cli/blob/main/CLAUDE.md

Fetch all tags from the remote and describe the latest tag to determine the current version. This is the first step in determining the next version.

```bash
git fetch origin --tags
git describe --tags --abbrev=0
```

--------------------------------

### Log Health Check Skipped for Authenticated Endpoints

Source: https://github.com/cortexapps/cli/blob/main/internal/axon/relay-improvements.md

This example shows a note to log when the REST API health check is skipped due to authentication requirements.

```text
Note: REST API health check skipped (integration requires authentication).
      The relay will authenticate requests at runtime.
```

--------------------------------

### Navigate to Internal Directory

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

Change directory to the internal tooling directory to access its specific commands and configurations.

```bash
cd internal/
```

--------------------------------

### Check Pipeline Pods

Source: https://github.com/cortexapps/cli/blob/main/internal/CLAUDE.md

List pipeline pods in the `default` namespace, sorted by creation timestamp, and filter for those related to Kratix.

```bash
# Check pipeline pods (look for recent ones)
kubectl get pods -n default --sort-by=.metadata.creationTimestamp | grep kratix
```

--------------------------------

### Run a Single Test File

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/specs/2026-04-06-github-workflow-action-block-tests-design.md

Execute tests from a specific file using the Justfile. This is useful for focused testing during development.

```bash
# Run a single test file
just test tests/functional/test_gh_branches.py

```

--------------------------------

### cortex workflows get-run

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/specs/2026-04-06-github-workflow-action-block-tests-design.md

Retrieves details of a specific workflow run using GET /api/v1/workflows/{tag}/runs/{runId}. Requires workflow tag and run ID.

```APIDOC
## cortex workflows get-run

### Description
Gets run details via `GET /api/v1/workflows/{tag}/runs/{runId}`.

### Method
GET

### Endpoint
`/api/v1/workflows/{tag}/runs/{runId}`

### Parameters
#### Command Line Options
- **-t, --tag** (TEXT) - Required - Workflow tag
- **-r, --run-id** (TEXT) - Required - Run ID
```

--------------------------------

### Iterate over all services

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Bash loop to iterate over all services, printing each service name. Assumes service tags are unique.

```bash
for service in `cortex catalog list -t service --csv -C tag --sort tag:asc`; do echo "service = $service"; done
```

--------------------------------

### Get Scorecard Next Steps

Source: https://context7.com/cortexapps/cli/llms.txt

Retrieves recommended improvement actions for a specific entity within a given scorecard. Requires the scorecard tag and the entity's tag or ID.

```bash
cortex scorecards next-steps \
  --scorecard-tag production-readiness \
  --tag-or-id my-service
```

--------------------------------

### backup import

Source: https://context7.com/cortexapps/cli/llms.txt

Imports tenant data from a backup directory into a Cortex tenant.

```APIDOC
## `backup import` — Import tenant data from disk

Imports a previously exported backup directory into a Cortex tenant, with parallel processing and a summary report.

### Usage
```bash
# Import from an export directory
cortex backup import --directory /Users/user/.cortex/export/2025-06-12-14-58-14-default

# Force-recreate already existing entities
cortex backup import -d /tmp/cortex-backup --force

# Cross-tenant migration example
cortex -t myTenant-dev backup export
cortex -t myTenant backup import -d ~/.cortex/export/2025-06-12-14-58-14-myTenant-dev
```

### Output Example
```
================================================================================
IMPORT SUMMARY
================================================================================
catalog:
  Imported: 47
scorecards:
  Imported: 5
TOTAL: 52 imported, 0 failed
```
```

--------------------------------

### Verify `cortex workflows get-run` command registration

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-07-gh-workflow-tests-minimal-slice.md

Run this command to verify that the `get-run` command and its options (`--tag`, `--run-id`) are correctly registered in the CLI.

```bash
poetry run cortex workflows get-run --help
```

--------------------------------

### SKE Operator Helm Values for Minikube

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/plans/2026-04-23-ske-cortex-integration-test.md

This YAML file defines the Helm values for the SKE Operator, intended for local minikube testing. Environment variables are expected to be substituted during installation.

```yaml
# SKE Operator Helm values for local minikube testing.
# Environment variables are substituted at install time via --set overrides.
#
# Usage (from Justfile):

```

--------------------------------

### Import Tenant Data

Source: https://context7.com/cortexapps/cli/llms.txt

Imports tenant data from a previously exported backup directory. Can force-recreate existing entities and is useful for cross-tenant migrations.

```bash
# Import from an export directory
cortex backup import --directory /Users/user/.cortex/export/2025-06-12-14-58-14-default
```

```bash
# Force-recreate already existing entities
cortex backup import -d /tmp/cortex-backup --force
```

```bash
# Cross-tenant migration example
cortex -t myTenant-dev backup export
cortex -t myTenant backup import -d ~/.cortex/export/2025-06-12-14-58-14-myTenant-dev
```

--------------------------------

### Raw REST API Access

Source: https://context7.com/cortexapps/cli/llms.txt

Execute arbitrary HTTP requests directly to the Cortex REST API. Supports GET, POST (with JSON body file), and DELETE methods. Specify the endpoint for the request.

```bash
cortex rest get --endpoint "api/v1/catalog/my-service"
```

```bash
cortex rest post --endpoint "api/v1/catalog/my-service/custom-data" -f body.json
```

```bash
cortex rest delete --endpoint "api/v1/catalog/old-service"
```

--------------------------------

### Run Cortexapps CLI using Docker

Source: https://github.com/cortexapps/cli/blob/main/README.rst

Run the Cortexapps CLI container, providing your API key and CLI arguments.

```bash
docker run -e CORTEX_API_KEY=<your API key> cortexapp/cli <Cortex CLI arguments>
```

--------------------------------

### Create Release PR to Main

Source: https://github.com/cortexapps/cli/blob/main/CLAUDE.md

Use this command to create a pull request from the staging branch to the main branch to trigger a release. Include the version number and a brief description in the title.

```bash
gh pr create --base main --head staging --title "Release X.Y.Z: Description"
```

--------------------------------

### Cortex Workflows Get Run CLI Command Options

Source: https://github.com/cortexapps/cli/blob/main/docs/superpowers/specs/2026-04-06-github-workflow-action-block-tests-design.md

Options for the `cortex workflows get-run` command, used to retrieve details of a specific workflow run. Requires workflow tag and run ID.

```bash
Options:
  -t, --tag        TEXT     Workflow tag [required]
  -r, --run-id     TEXT     Run ID [required]
```

--------------------------------

### Execute CQL Query

Source: https://context7.com/cortexapps/cli/llms.txt

Runs a Cortex Query Language (CQL) expression against the catalog. Can read queries from a file or stdin, and optionally wait for results.

```bash
# Run a CQL query from a file
cat > my-query.cql <<EOF
jq(entity.descriptor(), "[.info.\"x-cortex-owners\" | .[] | select(.type | ascii_downcase == \"group\") | select(.provider == null)] | length") > 0
EOF
cortex queries run --file my-query.cql
```

```bash
# Run from stdin and wait up to 600 seconds
cortex queries run -f- -w -x 600 <<EOF
entity.type() == "service" && scorecard("production-readiness").score() < 0.5
EOF
# Output:
# { "jobId": "job-xyz", "status": "DONE", "result": [ { "tag": "low-score-service" }, ... ] }
```

```bash
# Submit async and check status later
cortex queries run -f my-query.cql
# Output: { "jobId": "job-xyz789", "status": "PENDING" }
```

```bash
cortex queries get --job-id job-xyz789
# Output: { "jobId": "job-xyz789", "status": "DONE", "result": [...] }
```