Automating a Jira Service Management Knowledge Base

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

What lives in a Jira Service Management knowledge base

A Jira Service Management knowledge base is a library of self-service help articles that customers read from the portal and agents link into ticket replies. The articles themselves are not stored inside Jira. They live as pages in a Confluence space that is linked to your service project, and that linked space needs a Confluence product on the same site. That one architectural fact is what makes command-line automation possible: because every KB article is an ordinary Confluence page, atlassian-cli can create, search, label, audit, and export them with the same confluence commands it uses for any other space, plus a dedicated jsm kb search for the portal-side lookup.

The practical payoff is that KB maintenance stops being a two-tab chore. Instead of hopping between the JSM portal and the Confluence editor, you run one binary. You can script the boring parts (relabelling, stale-article sweeps, backups) and keep the writing in files your team already reviews in Git.

How this differs from acli

atlassian-cli is an independent, community open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with Atlassian. Use the official acli for first-party vendor support; use atlassian-cli if you want a single free Rust binary spanning Jira, Confluence, Bitbucket, and JSM in one command surface. Everything below is copy-pasteable atlassian-cli syntax. If you want the full list of subcommands and flags, keep the command reference open in another tab.

One setup note before the commands: authenticate once with a profile, then reuse it. Examples here assume a default profile; add --profile <name> to target a specific site. See the JSM CLI guide for the end-to-end auth walkthrough.

Search the knowledge base

The portal-facing search is the one command that is JSM-specific. It queries the knowledge base linked to a given service desk and returns the matching articles, exactly what a customer would see when they start typing in the help center. First, find the numeric service desk id:

# List service desks to get the numeric id
atlassian-cli jsm service-desk list --limit 25

Then search that desk's knowledge base for a term:

# Search the KB linked to service desk 10
atlassian-cli jsm kb search \
  --query "vpn" \
  --servicedesk-id 10 \
  --limit 25

This is the fastest way to answer "do we already have an article for this?" before an agent writes a fresh reply, and it is a good sanity check after publishing a new page: if the article does not surface for the obvious search term, the title or wording needs work. Pipe it to JSON when you want to feed the result list into another script:

# Machine-readable output for scripting
atlassian-cli jsm kb search \
  --query "password reset" \
  --servicedesk-id 10 \
  --format json | jq '.[].title'

Author articles as Confluence pages

There is no separate "kb article create" verb, and there does not need to be: a KB article is a Confluence page in the linked space. So you author with the confluence page commands. Start by finding the space key that backs your knowledge base:

# Find the Confluence space that backs the KB
atlassian-cli confluence space list --limit 25

Create a new article in that space. The body uses Confluence storage format (HTML-like), so simple markup goes straight in:

# Create a KB article in the KB space (key: HELP)
atlassian-cli confluence page create \
  --space HELP \
  --title "How to reset your VPN password" \
  --body "<p>Follow these steps to reset access.</p>"

Categorisation is what makes a knowledge base findable, and in Confluence that means labels. Tag the article so it groups correctly in the portal and in search:

# Label the article (page id from the create output)
atlassian-cli confluence page add-label 45678 vpn
atlassian-cli confluence page add-label 45678 self-service

# Update the article later
atlassian-cli confluence page update 45678 \
  --title "How to reset your VPN password (2026)"

# Check the edit history
atlassian-cli confluence page versions 45678

Because these are ordinary pages, the rest of the toolbox comes for free: confluence page comments to read reviewer feedback, confluence page get-restrictions to confirm who can edit, and confluence page get 45678 to pull the current content into a file for editing.

Docs-as-code: sync Markdown in

Most teams would rather write help articles in Markdown, review them in a pull request, and publish on merge, instead of editing in a browser. Since KB articles are just Confluence pages, that docs-as-code workflow applies directly. Author in Markdown, convert to Confluence storage format, and push. The mechanics are covered in depth in the docs-as-code with Confluence guide, and the full round-trip pipeline lives in the Markdown sync runbook.

The reverse direction is just as useful for review and backup: pull existing articles out to Markdown so writers can diff them, or archive them in version control. See exporting Confluence to Markdown for that flow. Once the content lives in files, the KB stops being a black box and starts behaving like the rest of your codebase.

Audit and prune stale articles

Knowledge bases rot. Articles go out of date, duplicates pile up, and nobody notices until a customer follows outdated steps. The CLI turns the audit into a query. Use CQL to find articles that have not been touched in a year, or pages that are missing the labels your taxonomy requires:

# Articles in the KB space not updated in the last year
atlassian-cli confluence search cql \
  "space = HELP and type = page and lastmodified < now('-365d')" \
  --limit 50

# Find pages missing a required label
atlassian-cli confluence search in-space HELP "vpn"

Usage data tells you which articles are worth the effort of updating and which are dead weight. Pull view counts for a specific article, or space-wide stats:

# How many people actually read this article?
atlassian-cli confluence analytics page-views 45678 --from 2026-01-01

# Space-level activity for the whole KB
atlassian-cli confluence analytics space-stats HELP

When you do decide to clean up, the bulk commands act on many articles at once, and every one of them supports --dry-run so you see exactly which pages are affected before anything changes. Always back up before you delete:

# 1. Back up the entire KB space first
atlassian-cli confluence bulk export \
  --cql "space = HELP" \
  --output kb-backup.json \
  --format json

# 2. Preview a relabel across the space
atlassian-cli confluence bulk add-labels \
  --cql "space = HELP" \
  --labels reviewed,2026 \
  --dry-run

# 3. Preview removal of clearly dead drafts
atlassian-cli confluence bulk delete \
  --cql "space = HELP and title ~ 'DRAFT'" \
  --dry-run

Drop the --dry-run flag only once the preview matches your intent. The same safety-first pattern is used for Jira in bulk Jira operations, and it is the single most important habit when scripting against a live knowledge base.

A weekly KB maintenance script

Here is a small script that ties the pieces together. Run it on a schedule to keep the knowledge base honest: back it up, flag stale articles for review, and print the ones that customers actually search for but that return nothing.

#!/bin/bash
# Weekly JSM knowledge base health check
set -euo pipefail

SPACE="HELP"        # Confluence space backing the KB
DESK="10"           # JSM service desk id
DATE=$(date +%F)

# 1. Snapshot the whole KB for safekeeping
atlassian-cli confluence bulk export \
  --cql "space = $SPACE" \
  --output "kb-$DATE.json" \
  --format json

# 2. List articles not updated in a year (review candidates)
atlassian-cli confluence search cql \
  "space = $SPACE and type = page and lastmodified < now('-365d')" \
  --format csv > "kb-stale-$DATE.csv"

# 3. Sanity-check common portal searches resolve to something
for term in "vpn" "password" "onboarding"; do
  hits=$(atlassian-cli jsm kb search --query "$term" \
    --servicedesk-id "$DESK" --format json | jq 'length')
  echo "$term -> $hits articles"
done

echo "KB health check complete: kb-$DATE.json"

Nothing here touches a live article without your say-so. It backs up, it reports, and it surfaces the gaps between what customers search for and what the knowledge base answers. That gap list is the most valuable thing a service team can have: it is a prioritised writing backlog, generated automatically.

FAQ

Related Resources