spectra

Appearance

Environment Variables ​

spectryn uses environment variables for sensitive configuration like API credentials. This page covers all supported variables and best practices.

Tracker Credentials ​

Jira ​

VariableDescriptionExample
JIRA_URLYour Jira instance URLhttps://company.atlassian.net
JIRA_EMAILYour Jira account emailyou@company.com
JIRA_API_TOKENJira API tokenATATT3xFf...
JIRA_PROJECTDefault project key (optional)PROJ

GitHub ​

VariableDescriptionExample
GITHUB_TOKENPersonal Access Tokenghp_xxxx...
GITHUB_OWNERRepository owneryour-org
GITHUB_REPORepository nameyour-repo
GITHUB_BASE_URLAPI URL (optional)https://api.github.com
GITHUB_PROJECT_NUMBERProjects v2 number (optional)1

GitLab ​

VariableDescriptionExample
GITLAB_TOKENPersonal Access Tokenglpat-xxxx...
GITLAB_PROJECT_IDProject ID or path12345 or group/project
GITLAB_BASE_URLAPI URL (optional)https://gitlab.com/api/v4
GITLAB_GROUP_IDGroup ID for epics (optional)mygroup

Azure DevOps ​

VariableDescriptionExample
AZURE_DEVOPS_ORGOrganization nameyour-org
AZURE_DEVOPS_PROJECTProject nameyour-project
AZURE_DEVOPS_PATPersonal Access Tokenxxxx...
AZURE_DEVOPS_BASE_URLBase URL (optional)https://dev.azure.com

Linear ​

VariableDescriptionExample
LINEAR_API_KEYAPI keylin_api_xxxx...
LINEAR_TEAM_IDTeam key or UUIDENG
LINEAR_PROJECT_IDProject UUID (optional)uuid...

Asana ​

VariableDescriptionExample
ASANA_ACCESS_TOKENPersonal Access Token1/xxxx...
ASANA_WORKSPACE_IDWorkspace GID1234567890
ASANA_PROJECT_IDProject GID0987654321

Trello ​

VariableDescriptionExample
TRELLO_API_KEYAPI keyxxxx...
TRELLO_API_TOKENAPI tokenxxxx...
TRELLO_BOARD_IDBoard IDabc123def

ClickUp ​

VariableDescriptionExample
CLICKUP_API_TOKENAPI tokenpk_xxxx...
CLICKUP_LIST_IDList ID (optional)123456
CLICKUP_SPACE_IDSpace ID (optional)789012

Shortcut ​

VariableDescriptionExample
SHORTCUT_API_TOKENAPI tokenxxxx...
SHORTCUT_WORKSPACE_IDWorkspace UUID or slugmy-workspace

Monday.com ​

VariableDescriptionExample
MONDAY_API_TOKENAPI token (v2)xxxx...
MONDAY_BOARD_IDBoard ID1234567890
MONDAY_WORKSPACE_IDWorkspace ID (optional)9876543

Plane ​

VariableDescriptionExample
PLANE_API_TOKENAPI tokenxxxx...
PLANE_WORKSPACE_SLUGWorkspace slugmy-workspace
PLANE_PROJECT_IDProject UUIDuuid...
PLANE_API_URLAPI URL (optional)https://app.plane.so/api/v1

YouTrack ​

VariableDescriptionExample
YOUTRACK_URLYouTrack URLhttps://youtrack.mycompany.com
YOUTRACK_TOKENPermanent tokenperm:xxxx...
YOUTRACK_PROJECT_IDProject IDPROJ

Bitbucket ​

VariableDescriptionExample
BITBUCKET_USERNAMEUsernameyour-username
BITBUCKET_APP_PASSWORDApp Passwordxxxx...
BITBUCKET_WORKSPACEWorkspace slugmy-workspace
BITBUCKET_REPORepository slugmy-repo

Basecamp ​

VariableDescriptionExample
BASECAMP_ACCESS_TOKENOAuth access tokenxxxx...
BASECAMP_ACCOUNT_IDAccount ID1234567
BASECAMP_PROJECT_IDProject ID7654321

Pivotal Tracker ​

VariableDescriptionExample
PIVOTAL_API_TOKENAPI tokenxxxx...
PIVOTAL_PROJECT_IDProject ID1234567

General Settings ​

VariableDescriptionDefault
SPECTRA_VERBOSEEnable verbose outputfalse
SPECTRA_LOG_LEVELLogging levelINFO
SPECTRA_NO_COLORDisable colored outputfalse
SPECTRA_CONFIGConfig file path.spectryn.yaml

Setting Environment Variables ​

Temporary (Current Session) ​

bash
export GITHUB_TOKEN=ghp_your-token
export GITHUB_OWNER=your-org
export GITHUB_REPO=your-repo
fish
set -x GITHUB_TOKEN ghp_your-token
set -x GITHUB_OWNER your-org
set -x GITHUB_REPO your-repo
powershell
$env:GITHUB_TOKEN = "ghp_your-token"
$env:GITHUB_OWNER = "your-org"
$env:GITHUB_REPO = "your-repo"

Permanent (.env File) ​

Create a .env file in your project directory:

bash
# .env - Choose your tracker

# GitHub
GITHUB_TOKEN=ghp_your-token
GITHUB_OWNER=your-org
GITHUB_REPO=your-repo

# Or Jira
# JIRA_URL=https://your-company.atlassian.net
# JIRA_EMAIL=your.email@company.com
# JIRA_API_TOKEN=your-api-token

# Or Linear
# LINEAR_API_KEY=lin_api_your-key
# LINEAR_TEAM_ID=ENG

# General settings
SPECTRA_VERBOSE=true

spectryn automatically loads .env files from:

  1. Current working directory
  2. Home directory (~/.env)

Security Warning

Never commit .env files to version control!

Add to your .gitignore:

bash
.env
.env.local
.env.*.local

Getting API Tokens ​

Jira ​

  1. Go to Atlassian Account Settings
  2. Click Create API token
  3. Give it a descriptive name (e.g., "spectryn CLI")
  4. Copy the token immediately

GitHub ​

  1. Go to Settings → Developer settings → Personal access tokens
  2. Click Generate new token (classic)
  3. Select scopes: repo, project (if using Projects)
  4. Copy the token (starts with ghp_)

GitLab ​

  1. Go to User Settings → Access Tokens
  2. Create a new token with api scope
  3. Copy the token (starts with glpat-)

Linear ​

  1. Go to Settings → API → Personal API keys
  2. Click Create key
  3. Copy the key (starts with lin_api_)

Azure DevOps ​

  1. Go to User Settings → Personal access tokens
  2. Click + New Token
  3. Select scopes: Work Items (Read & Write)
  4. Copy the token

Asana ​

  1. Go to My Settings → Apps → Developer Console
  2. Click Create new token
  3. Copy the token

Token Best Practices

  • Create a dedicated token for spectryn
  • Use a descriptive name for auditing
  • Rotate tokens periodically (every 90 days)
  • Revoke tokens when no longer needed

CI/CD Configuration ​

GitHub Actions ​

yaml
# .github/workflows/sync.yml
jobs:
  sync-jira:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install spectryn
        run: pip install spectryn

      - name: Sync to Jira
        env:
          JIRA_URL: ${{ secrets.JIRA_URL }}
          JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
        run: |
          spectryn --markdown EPIC.md --epic PROJ-123 --execute --no-confirm

GitLab CI ​

yaml
# .gitlab-ci.yml
sync-jira:
  image: python:3.12
  variables:
    JIRA_URL: $JIRA_URL
    JIRA_EMAIL: $JIRA_EMAIL
    JIRA_API_TOKEN: $JIRA_API_TOKEN
  script:
    - pip install spectryn
    - spectryn --markdown EPIC.md --epic PROJ-123 --execute --no-confirm

Docker ​

bash
docker run --rm \
  -e JIRA_URL=$JIRA_URL \
  -e JIRA_EMAIL=$JIRA_EMAIL \
  -e JIRA_API_TOKEN=$JIRA_API_TOKEN \
  -v $(pwd):/workspace \
  adrianthehactus/spectryn:latest \
  --markdown EPIC.md --epic PROJ-123 --execute

Troubleshooting ​

Token Not Working ​

If you get authentication errors:

  1. Check token validity - Tokens expire and can be revoked
  2. Verify email - Must match the account that created the token
  3. Check URL - Must include https:// and be the correct domain
  4. Test with curl:
bash
curl -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_URL/rest/api/3/myself"

Environment Not Loading ​

If .env isn't being loaded:

  1. Check file location (same directory as running command)
  2. Verify file syntax (no quotes around values, no spaces around =)
  3. Try explicit loading:
bash
source .env && spectryn --markdown EPIC.md --epic PROJ-123

Released under the MIT License.

Copyright © 2025 Adrian Darian