Advanced CLI Usage

CI/CD integration, shell scripting, automated monitoring, and power-user patterns for the Skytells CLI.

CI/CD integration

GitHub Actions

Deploy on every push to main:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Skytells CLI
        run: npm install -g @skytells/cli

      - name: Deploy
        env:
          SKYTELLS_TOKEN: ${{ secrets.SKYTELLS_TOKEN }}
          SKYTELLS_ACCESS_KEY: ${{ secrets.SKYTELLS_ACCESS_KEY }}
        run: |
          skytells deploy ${{ vars.APP_ID }}

      - name: Verify deployment
        env:
          SKYTELLS_TOKEN: ${{ secrets.SKYTELLS_TOKEN }}
          SKYTELLS_ACCESS_KEY: ${{ secrets.SKYTELLS_ACCESS_KEY }}
        run: |
          STATUS=$(skytells deployments ls --app ${{ vars.APP_ID }} --limit 1 --json | jq -r '.[0].status')
          echo "Deployment status: $STATUS"
          [ "$STATUS" = "success" ] || exit 1

Store SKYTELLS_TOKEN and SKYTELLS_ACCESS_KEY in your repository's Secrets (not Variables). Generate a token at console.skytells.ai/settings/tokens and find your project access key in project settings.


GitLab CI

deploy:
  stage: deploy
  image: node:20
  script:
    - npm install -g @skytells/cli
    - skytells deploy $APP_ID
  variables:
    SKYTELLS_TOKEN: $CI_SKYTELLS_TOKEN
    SKYTELLS_ACCESS_KEY: $CI_SKYTELLS_ACCESS_KEY
  only:
    - main

Environment variable injection

Set environment variables during a CI deployment:

skytells env set --app $APP_ID \
  COMMIT_SHA=$CI_COMMIT_SHA \
  BUILD_NUMBER=$CI_BUILD_NUMBER

skytells apps redeploy $APP_ID

Scripting with JSON output

Every command supports --json. Combine with jq for powerful automation:

# Get all running app IDs
skytells apps ls --json | jq -r '.[] | select(.status == "running") | .id'

# Check if a deployment succeeded
RESULT=$(skytells deployments ls --app my-api --limit 1 --json)
STATUS=$(echo "$RESULT" | jq -r '.[0].status')
echo "Last deployment: $STATUS"

# Extract all environment variable keys
skytells env ls --json | jq -r '.[].key'

# Get project name
skytells project --json | jq -r '.name'

# Count failed executions today
skytells orchestrator executions --status failed --json | jq 'length'

Automation patterns

Automated deploy-and-verify script

#!/bin/bash
set -euo pipefail

APP_ID="${1:?Usage: deploy.sh <app-id>}"

echo "Deploying $APP_ID..."
skytells deploy "$APP_ID" --json

echo "Waiting for deployment..."
for i in $(seq 1 30); do
  STATUS=$(skytells deployments ls --app "$APP_ID" --limit 1 --json | jq -r '.[0].status')
  echo "  Status: $STATUS"
  [ "$STATUS" = "success" ] && echo "Deploy succeeded." && exit 0
  [ "$STATUS" = "failed" ] && echo "Deploy failed." && exit 1
  sleep 10
done

echo "Timed out waiting for deployment."
exit 1

Cognition event polling

Poll for new Cognition events continuously:

#!/bin/bash
LAST_EVENT=""

while true; do
  if [ -z "$LAST_EVENT" ]; then
    RESULT=$(skytells cognition events --limit 10 --json)
  else
    RESULT=$(skytells cognition events --since "$LAST_EVENT" --json)
  fi

  echo "$RESULT"

  NEW_LAST=$(echo "$RESULT" | jq -r '.[-1].id // empty')
  [ -n "$NEW_LAST" ] && LAST_EVENT="$NEW_LAST"

  sleep 300
done

For real-time Cognition observability, this pattern enables lightweight alerting without a full monitoring stack.


Orchestrator failure alerting

Check for failed workflow executions and output a report:

#!/bin/bash
FAILED=$(skytells orchestrator executions --status failed --limit 20 --json)
COUNT=$(echo "$FAILED" | jq 'length')

if [ "$COUNT" -gt 0 ]; then
  echo "WARNING: $COUNT failed executions"
  echo "$FAILED" | jq -r '.[] | "\(.id) — \(.workflow) — \(.started_at)"'
fi

Power-user patterns

Inspect all apps across projects

If you manage multiple projects, loop through them by switching access keys:

for KEY in sk_proj_one sk_proj_two sk_proj_three; do
  export SKYTELLS_ACCESS_KEY="$KEY"
  echo "=== Project: $(skytells project --json | jq -r '.name') ==="
  skytells apps ls
done

Set multiple environment variables from a file

# .env.production (one KEY=value per line, no spaces around =)
while IFS='=' read -r KEY VALUE; do
  # Skip comments and blank lines
  [[ "$KEY" =~ ^#|^$ ]] && continue
  PAIRS+=("${KEY}=${VALUE}")
done < .env.production

skytells env set --app "$APP_ID" "${PAIRS[@]}"

Combine logs with timestamps for debugging

# Pipe to ts (moreutils) for timestamps
skytells logs my-api --follow | ts '[%Y-%m-%d %H:%M:%S]'

Security considerations

How is this guide?

On this page