Installation and First-Time Setup

This page is the recommended starting point for new customers. It takes a workstation from “nothing installed” to “first successful Automation export and inventory report” in the right order. Each step validates the previous one before the next step touches a larger surface area.

At the end of this page you will have a signed ajat binary on PATH, an activated license, Jira Cloud credentials configured through a file or environment variables, a green ajat doctor result, a local export tree of Automation JSON files, and a self-contained inventory report.

Before you begin

Make sure you have:

• a Jira Cloud site such as acme.atlassian.net — Jira Server and Jira Data Center are not supported
• a Jira account with permission to read Automation rules across the scope you intend to export (and, for mutation workflows, the matching Automation management permissions)
• a Jira API token created for that Atlassian account
• network access from the workstation or CI runner to the Jira Cloud site and api.atlassian.com — corporate proxies can be set through http.client.proxy or AJAT_HTTP_CLIENT_PROXY
• a valid ajat license from store.climakers.com/ajat, or an offline machine-bound license file issued by Climakers support
• enough local disk space for the export tree and reports
• administrator rights only for the install step, if your platform requires it

Step 1: Download and install the released package

ajat is delivered through the Climakers store. Purchase a plan or start a free trial at store.climakers.com/ajat. After checkout, your order page and confirmation email list a download link for every released package and its matching .sha256 checksum file:

• ajat-<version>-darwin-universal.pkg — macOS installer (Apple Silicon and Intel)
• ajat-<version>-linux-amd64.zip — Linux x86-64
• ajat-<version>-linux-arm64.zip — Linux ARM64
• a matching .sha256 checksum file for each package

Download the package for your platform together with its .sha256 file into the same folder, then follow the section that matches your workstation.

Install on macOS

ajat for macOS is a signed, notarized universal .pkg installer for Apple Silicon and Intel systems. Download ajat-<version>-darwin-universal.pkg and its .sha256 from your order, then verify and install (set VERSION to the version shown in your order):

VERSION=v1.0.0   # use the version shown in your Climakers order
shasum -a 256 -c "ajat-${VERSION}-darwin-universal.sha256"
sudo installer -pkg "ajat-${VERSION}-darwin-universal.pkg" -target /

You can also open the .pkg with a double click in Finder and follow the installer prompts.

Install on Linux

ajat for Linux is delivered as a per-architecture .zip archive with a matching .sha256 checksum file. Download the archive for your CPU architecture (amd64 or arm64) and its .sha256 from your order, then verify and place the binary on PATH:

VERSION=v1.0.0   # use the version shown in your Climakers order
ARCH=amd64       # or arm64
sha256sum -c "ajat-${VERSION}-linux-${ARCH}.sha256"
unzip -q -o "ajat-${VERSION}-linux-${ARCH}.zip"
chmod +x ajat
sudo mv ajat /usr/local/bin/ajat

Step 2: Confirm the installation

Verify the binary and inspect the command surface before moving on:

ajat version
ajat --help
ajat tree --short

ajat tree --short is the fastest way to confirm that the full command surface is available without reading the reference. You can also print the resolved config and license paths at any time:

ajat config where
ajat license where

Step 3: Review and activate the license

ajat is commercial software. Setup and diagnostic commands (config, doctor, license, support, tree, version, help, and completion) run without a license, but operational commands such as export, report, diff, search, import, rule, and invoke require a valid one.

The license agreement is embedded in the binary and can be reviewed offline:

ajat license terms

Activate a purchased license key:

ajat license activate --license-key YOUR_LICENSE_KEY
ajat license list

For an air-gapped or restricted environment, activate the machine-bound license file issued by Climakers support instead:

ajat license activate --license-file ./ajat-license.bin
ajat license list

Verify activation:

ajat license validate

Step 4: Create the configuration file

Create the default config file and print its resolved path:

ajat config create
ajat config where

Default locations:

Configuration precedence is: command-line flags, then AJAT_ environment variables, then the config file, then defaults.

Step 5: Generate a Jira API token

Create a token at id.atlassian.com/manage-profile/security/api-tokens for the Atlassian account that will operate ajat.

You need:

• your Jira Cloud domain, for example acme.atlassian.net
• your Atlassian account email — Jira Cloud API auth uses the email, not a display name
• the generated API token

Step 6: Configure Jira credentials

The domain is the bare hostname. Do not include https://, a trailing slash, or a /wiki suffix.

Use the config file

jira:
  domain: acme.atlassian.net
  username: you@acme.com
  api_token: YOUR_API_TOKEN

Use CLI commands

ajat config set jira.domain acme.atlassian.net
ajat config set jira.username you@acme.com
ajat config set jira.api_token YOUR_API_TOKEN

Use environment variables

For CI/CD, prefer environment variables and store the token as a secret.

export AJAT_JIRA_DOMAIN=acme.atlassian.net
export AJAT_JIRA_USERNAME=you@acme.com
export AJAT_JIRA_API_TOKEN=YOUR_API_TOKEN

env:
  AJAT_JIRA_DOMAIN: acme.atlassian.net
  AJAT_JIRA_USERNAME: ${{ secrets.JIRA_USERNAME }}
  AJAT_JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}

Inspect the effective configuration safely at any time — jira.api_token is masked in output:

ajat config list
ajat config get jira.domain
ajat config validate --require-credentials

Step 7: Run doctor

Run the readiness check before you touch a real export:

ajat doctor

Doctor validates configuration, license readability and local license metadata, tenant resolution, Jira credentials, Automation manual-rule API access, and output-directory writability in one step.

Sample output from a real workstation session, with tenant and machine details redacted:

🩺 Running diagnostics for ajat v1.0.0...

  ✅  Configuration file           /Users/<user>/Library/Application Support/ajat/config.yaml
  ✅  Jira credentials             <tenant>.atlassian.net (user: <redacted>)
  ✅  Jira Cloud API               connected (287ms)
  ✅  Automation API               manual-rule access confirmed
  ✅  License file                 loaded (<redacted>)
  ✅  License validation           active (<redacted>)
  ✅  Output directory             writable
  ✅  Version                      ajat v1.0.0 (darwin/arm64, built 2026-03-29T08:23:49Z)

📊 Result: all 8 checks passed

🎉 ajat is ready to use!

To validate a specific export destination before the first run:

ajat doctor --output-dir ./jira-automations-backup

Step 8: Run the first export and inventory report

Export the automation estate into a scope-aware JSON tree, then build a self-contained inventory report from it. Reports read the local tree and do not call Jira.

ajat export --output-dir ./jira-automations-backup
 
ajat report inventory \
  --input-dir ./jira-automations-backup \
  --output-file inventory.html

Open the report locally:

open inventory.html        # macOS
xdg-open inventory.html    # Linux

After this first run, keep the same export directory for incremental refreshes. ajat uses .ajat_state.json to skip unchanged rules and retry failed ones.

If something fails

Use this order:

• re-run ajat doctor to confirm the environment
• verify the active config file with ajat config where and the license state with ajat license validate
• capture structured logs with ajat --debug --log-file ./ajat.log <command>
• generate a masked diagnostic bundle with ajat support --log-file ./ajat.log --output support-bundle.txt when contacting Climakers support

What to read next

• Export the estate for state handling, incremental refresh, rate limits, and the on-disk layout
• HTML Reports for the five reports and secure sharing guidance
• Compare Snapshots for drift review and CI drift gates
• Bulk Rule Operations and Import and Restore for safe, plan-first mutations
• Configuration for precedence, environment variables, and proxy settings