Installation

This guide will walk you through installing jarkdown and setting up the required authentication.

Prerequisites

  • Python 3.8 or higher

  • A Jira account with API access

  • An Atlassian API token

Install from PyPI

Once published to PyPI, you’ll be able to install with:

pip install jarkdown

Install from Source

For the latest development version or to contribute:

# Clone the repository
git clone https://github.com/yourusername/jarkdown.git
cd jarkdown

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

Authentication Setup

jarkdown requires three environment variables for authentication:

1. Get Your Atlassian API Token

  1. Log in to your Atlassian account

  2. Go to Account Settings

  3. Click “Create API token”

  4. Give it a descriptive name (e.g., “jarkdown”)

  5. Copy the generated token - you won’t be able to see it again!

2. Create Environment File

Create a .env file in your project directory:

# .env
JIRA_DOMAIN=yourcompany.atlassian.net
JIRA_EMAIL=your.email@company.com
JIRA_API_TOKEN=your_api_token_here

Security Note: Never commit the .env file to version control! It’s already included in .gitignore.

3. Alternative: Export Variables

You can also export the variables in your shell:

export JIRA_DOMAIN=yourcompany.atlassian.net
export JIRA_EMAIL=your.email@company.com
export JIRA_API_TOKEN=your_api_token_here

For permanent setup, add these to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Verify Installation

Test that everything is working:

# Check the installation
jarkdown --help

# Test with a known issue
jarkdown PROJ-123

If you see the issue downloaded successfully, you’re all set!

Troubleshooting

Command not found

If jarkdown isn’t recognized:

# Ensure you're in the virtual environment
which python

# Reinstall
pip install -e .

Authentication errors

  • 401 Unauthorized: Check your email and API token are correct

  • Domain not found: Verify JIRA_DOMAIN doesn’t include https://

  • Missing variables: Ensure all three environment variables are set

Permission denied

On Unix-like systems, you might need to make the script executable:

chmod +x jarkdown

Next Steps