auth-setup

You are helping the user configure authentication for a StackQL provider.

Provider: $0

Follow these steps in order.

Step 1 - Check StackQL is installed

command -v stackql

If not found, delegate to /stackql-skills:install-stackql and then continue.

Step 2 - Check if the provider is pulled

stackql exec "SHOW PROVIDERS;" --output json

If the provider is not installed, delegate to /stackql-skills:pull-provider <provider> and then continue.

Step 3 - Determine auth method for the provider

Google (google)

Google supports two auth types:

Option A - Service account key file (non-interactive):

{
  "google": {
    "type": "service_account",
    "credentialsfilepath": "/path/to/sa-key.json"
  }
}

Ask the user for the path to their service account JSON key file.

Option B - Interactive (via gcloud):

{
  "google": {
    "type": "interactive"
  }
}

Requires gcloud auth login to have been run. Check:

command -v gcloud && gcloud auth list --filter=status:ACTIVE --format="value(account)" 2>/dev/null

AWS (awscc or aws)

AWS uses environment variables or credentials file:

{
  "aws": {
    "type": "aws_signing_v4",
    "credentialsenvvar": "AWS_SECRET_ACCESS_KEY",
    "keyIDenvvar": "AWS_ACCESS_KEY_ID"
  }
}

Check if credentials are available:

echo "${AWS_ACCESS_KEY_ID:+set}" "${AWS_SECRET_ACCESS_KEY:+set}"
test -f "$HOME/.aws/credentials" && echo "aws credentials file exists"

Azure (azure)

Azure supports service principal or interactive auth:

Option A - Service principal (env vars):

{
  "azure": {
    "type": "azure_default"
  }
}

Requires: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET

Check:

echo "${AZURE_TENANT_ID:+set}" "${AZURE_CLIENT_ID:+set}" "${AZURE_CLIENT_SECRET:+set}"

Option B - Interactive (via az cli):

Requires az login to have been run. Check:

command -v az && az account show --output json 2>/dev/null

GitHub (github)

{
  "github": {
    "type": "basic",
    "credentialsenvvar": "GITHUB_TOKEN"
  }
}

Check:

echo "${GITHUB_TOKEN:+set}"

Other providers

For providers not listed above, check the provider docs:

I don't have specific auth instructions for <provider>. Check the provider documentation at https://<provider>.stackql.io/ or use /stackql-skills:stackql-docs <provider> authentication to search for auth setup guidance.

Step 4 - Build the auth JSON

Based on the user's chosen auth method and credentials, construct the --auth JSON string.

Step 5 - Test the connection

Run a simple query to verify auth works:

stackql exec "SHOW SERVICES IN <provider>;" --auth='<AUTH_JSON>' --output json

If this fails with an auth error, help troubleshoot:

• Check credential file paths exist
• Verify env vars are set
• Suggest re-authenticating (gcloud auth login, az login, etc.)

Step 6 - Persist (optional)

Ask the user if they want to persist the auth configuration. Options:

Option A - Environment variable: Suggest adding to shell profile:

export STACKQL_AUTH='<AUTH_JSON>'

Then StackQL can be invoked as:

stackql exec "<SQL>" --auth="${STACKQL_AUTH}"

Option B - .stackqlrc file: Create or update a .stackqlrc file:

# .stackqlrc - StackQL configuration
AUTH='<AUTH_JSON>'

Note: Warn the user not to commit credential files or auth JSON containing secrets to version control.

Step 7 - Report

Confirm auth is working and suggest next steps:

Authentication for <provider> is configured. You can now:

• Explore resources: /stackql-skills:explore <provider>
• Run queries: /stackql-skills:query "SELECT ... FROM <provider>.<service>.<resource> WHERE ..."