CLI Setup

The jd CLI lets terminal-based AI agents (like Claude Code) and humans interact with AgentGate from the command line. It's also useful for scripting and CI/CD pipelines.

Installation

npm install -g @orbiscend/jd-cli

Verify the installation:

jd --version

Initial Configuration

Run the interactive setup:

jd init --global

This prompts you for:

1. Endpoint URL — copy from Jira → Apps → AgentGate for Jira - Tokens
2. API Token — your jfa_ token
3. Default Project — your Jira project key (e.g., PROJ)

The config is saved to ~/.agentgate-for-jira/config.json and is also read by the MCP server automatically.

Project-Level Config

For project-specific settings, run jd init (without --global) in your project directory. This creates .agentgate-for-jira/config.json in the current directory, which takes priority over the global config.

Manual Configuration

You can also set config values individually:

jd config set endpoint "https://your-endpoint-url"
jd config set token "jfa_your_token"
jd config set project "PROJ"

Or use environment variables (JD_ENDPOINT, JD_TOKEN, JD_PROJECT) — these take highest priority.

Verify Your Connection

jd status

This shows your connection status, token validity, and the authenticated user. Then:

jd prime

This shows your project overview: in-progress issues, pending changes, and tips.

Command Reference

Session

Command	Description
jd prime	Project overview: in-progress issues, pending changes, tips
jd status	Connection and token status

Issues

Command	Description
jd issues list	List issues (add --status, --assignee, --labels, --jql filters)
jd issues show KEY	Full issue details
jd issues show KEY -c	Full context: parent, children, links, recent comments
jd issues children KEY	List child issues
jd issues transition KEY "STATUS"	Move issue to new status (pending approval)
jd issues assign KEY "NAME"	Assign issue (pending approval)

Changes

Command	Description
jd changes create --type TYPE	Propose a change (create, update, transition, delete)
jd changes list	List changes (add --status pending/approved/rejected/failed)
jd changes show ID	View change details and diff
jd changes update ID	Modify a pending change
jd changes cancel ID	Cancel a pending change
jd changes approve ID	Approve a pending change
jd changes reject ID --reason "..."	Reject with reason

Comments

Command	Description
jd comment KEY --body "TEXT"	Add comment to issue (pending approval)

Configuration

Command	Description
jd init	Interactive setup (local config)
jd init --global	Interactive setup (global config)
jd config show	Show current config and sources
jd config set KEY VALUE	Set a config value
jd config unset KEY	Remove a config value

Other

Command	Description
jd workflow describe	Show project workflow (issue types and status transitions)
jd autocomplete [SHELL]	Set up shell tab completion (zsh, bash, PowerShell)

Global Flags

These flags work with any command and override config file settings:

Flag	Description
--json	Output as JSON (useful for scripting and AI agents)
--endpoint URL	Override endpoint URL
--project KEY	Override default project
--token TOKEN	Override API token

Shell Completion

Set up tab completion for faster command entry:

jd autocomplete zsh    # or bash, powershell

Follow the printed instructions to add the completion script to your shell profile.

Exit Codes

Code	Meaning
0	Success
1	Usage or configuration error
2	API or service error
3	Authentication error
4	Internal error

Custom PRIME.md

Customize jd prime output by creating .agentgate-for-jira/PRIME.md in your project directory. Available placeholders:

Placeholder	Replaced with
{{project}}	Current project key
{{pending_count}}	Number of pending changes
{{failed_count}}	Number of failed changes
{{pending_changes}}	Formatted list of pending changes
{{failed_changes}}	Formatted list of failed changes

This is useful for embedding project-specific workflow rules or instructions that your AI agent should follow.