Your First Sync

A complete walkthrough of setting up spectryn and syncing your first epic to Jira.

Duration: ~5 minutes

🎬

Terminal Recording

Step 1: Install spectryn

# Install with pip
$ pip install spectryn
Collecting spectryn
  Downloading spectryn-1.0.0-py3-none-any.whl (45 kB)
Installing collected packages: spectryn
Successfully installed spectryn-1.0.0

# Verify installation
$ spectryn --version
spectryn version 1.0.0

Alternative Installation

You can also use pipx install spectryn for an isolated environment, or install via Homebrew on macOS (see Installation Guide).

Step 2: Configure Credentials

# Create a .env file with your Jira credentials
$ cat > .env << 'EOF'
JIRA_URL=https://your-company.atlassian.net
JIRA_EMAIL=your.email@company.com
JIRA_API_TOKEN=your-api-token-here
EOF

# Verify file was created
$ cat .env
JIRA_URL=https://your-company.atlassian.net
JIRA_EMAIL=your.email@company.com
JIRA_API_TOKEN=your-api-token-here

Security

Add .env to your .gitignore to avoid committing secrets!

echo ".env" >> .gitignore

Getting Your API Token

1. Go to Atlassian Account

Visit id.atlassian.com/manage-profile/security/api-tokens

2. Create API Token

Click "Create API token" and give it a name like "spectryn"

3. Copy the Token

Copy immediately - you won't see it again!

Step 3: Create Your Epic Markdown

$ cat > EPIC.md << 'EOF'
# 🚀 My First Epic

> **Epic: Getting started with spectryn**

---

## User Stories

---

### 🔧 US-001: Setup Development Environment

| Field | Value |
|-------|-------|
| **Story Points** | 3 |
| **Priority** | 🔴 Critical |
| **Status** | 📋 Planned |

#### Description

**As a** developer
**I want** the development environment configured
**So that** I can start building features

#### Acceptance Criteria

- [ ] All dependencies installed
- [ ] Development server runs
- [ ] Tests pass

#### Subtasks

| # | Subtask | Description | SP | Status |
|---|---------|-------------|:--:|--------|
| 1 | Install deps | Run npm install | 1 | 📋 Planned |
| 2 | Configure env | Set up .env file | 1 | 📋 Planned |
| 3 | Verify setup | Run test suite | 1 | 📋 Planned |

---
EOF

Step 4: Preview Changes (Dry Run)

$ spectryn --markdown EPIC.md --epic PROJ-123

╭──────────────────────────────────────────────────────────────╮
│  spectryn v1.0.0                                              │
│  Syncing: EPIC.md → PROJ-123                                 │
│  Mode: DRY RUN (use --execute to apply changes)              │
╰──────────────────────────────────────────────────────────────╯

📋 Found 1 story in markdown

Matching stories with Jira...
  ✓ US-001 matched → PROJ-124 (fuzzy: 92%)

┌─────────────────────────────────────────────────────────────┐
│ US-001: Setup Development Environment                       │
│ Jira: PROJ-124                                              │
├─────────────────────────────────────────────────────────────┤
│ 📝 Would update description                                 │
│ ➕ Would create 3 subtasks                                  │
│ ✓ Status unchanged (Planned)                                │
└─────────────────────────────────────────────────────────────┘

Summary:
  Stories: 1
  Subtasks to create: 3
  Descriptions to update: 1

This is a dry run. No changes were made.
To apply these changes, add --execute flag.

Step 5: Execute the Sync

$ spectryn --markdown EPIC.md --epic PROJ-123 --execute

╭──────────────────────────────────────────────────────────────╮
│  spectryn v1.0.0                                              │
│  Syncing: EPIC.md → PROJ-123                                 │
│  Mode: EXECUTE                                               │
╰──────────────────────────────────────────────────────────────╯

⚠️  This will modify 1 story in Jira. Continue? [y/N]: y

💾 Creating backup... backup_20250113_143000

Syncing stories ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 1/1

✓ PROJ-124: Setup Development Environment
  ✓ Updated description
  ✓ Created subtask PROJ-125: Install deps
  ✓ Created subtask PROJ-126: Configure env
  ✓ Created subtask PROJ-127: Verify setup

╭──────────────────────────────────────────────────────────────╮
│  ✅ Sync Complete                                            │
│                                                              │
│  Stories synced: 1                                           │
│  Subtasks created: 3                                         │
│  Duration: 2.1s                                              │
│                                                              │
│  Backup: backup_20250113_143000                              │
╰──────────────────────────────────────────────────────────────╯

Step 6: Verify in Jira

After syncing, check your Jira epic:

PROJ-123 (Epic) └── PROJ-124: Setup Development Environment - Description updated ✓ - 3 subtasks created ✓ └── PROJ-125: Install deps └── PROJ-126: Configure env └── PROJ-127: Verify setup

What's Next?

🎮 Interactive Mode
Step-by-step guided sync💾 Backup & Restore
Safe sync with rollback📐 Schema Reference
Complete markdown format