jira

orbit CLI を使った Jira 操作

orbit CLI を使用して、Jira の課題、エピック、スプリント、ボード、プロジェクト、リリース、カスタムフィールド、画面、ステータス、課題タイプを管理します。Jira Cloud（REST API v3）と Jira Server/Data Center（REST API v2）の両方に対応しており、複数のプロファイルと 1Password のシークレット解決をサポートしています。

前提条件

1. orbit CLI がインストールされていること — which orbit が失敗する場合は、次のいずれかでインストールしてください。
   • macOS/Linux（Homebrew）： brew install jorgemuza/tap/orbit
   • macOS/Linux（スクリプト）： curl -sSfL https://raw.githubusercontent.com/jorgemuza/orbit/main/install.sh | sh
   • Windows（Scoop）： scoop bucket add jorgemuza https://github.com/jorgemuza/scoop-bucket && scoop install orbit
2. ~/.config/orbit/config.yaml に jira-cloud または jira-onprem サービスを設定したプロファイルがあること
3. 有効な認証情報 — Cloud の場合は API トークン（メールアドレスとトークンによる基本認証）、Server の場合は PAT
4. 認証情報は、1Password（op://）または Infisical（infisical://）の参照として保存し、自動解決できます

クイックリファレンス

すべてのコマンドは次の形式です：orbit -p <profile> jira <resource> <action> [flags]

コマンドツリーはここで終わります。<action> は常に末端の要素であり、<action> list はありません。読み取りには書き込みとは別のアクション名を使います。コメントの読み取りには issue view --comments を使い、issue comment はコメントの書き込み専用です。添付ファイルの一覧表示には issue attachments を使い、issue attach はアップロード専用です。サブコマンドを推測するのは、単に間違えるだけでなく危険です。書き込みアクションでは、課題キーを最初の位置引数として受け取るため、jira issue comment list PROJ-123 は課題キーが list、本文が PROJ-123 として解析され、実際の書き込みとして Jira に送信されます。推測するのではなく、references/commands.md を確認してください。

-o フラグで出力形式を指定します：table（デフォルト）、json、yaml。

コマンドとフラグの詳細については、references/commands.md を参照してください。 Jira Wiki マークアップの書式については（Server のみ）、references/wiki-markup.md を参照してください。

主なワークフロー

課題の表示

# View issue with comments (shows last 10 by default)
orbit -p myprofile jira issue view PROJ-123

# View with more comments
orbit -p myprofile jira issue view PROJ-123 --comments 50

# JSON output (includes full data + all comments)
orbit -p myprofile jira issue view PROJ-123 -o json

view コマンドでは、概要、タイプ、ステータス、優先度、担当者、報告者、ラベル、コンポーネント、説明、サブタスク、リンク、添付ファイル（ファイル名、サイズ、ダウンロード URL を含む）、コメントと投稿者／日付／編集日時が表示されます。コメント本文で参照されているスクリーンショットを確認しやすいように、添付ファイルはコメントの前に表示されます。

課題の作成

# Simple story
orbit -p myprofile jira issue create --project PROJ --type Story --summary "Add login page"

# Bug with priority and assignment
orbit -p myprofile jira issue create --project PROJ --type Bug \
  --summary "Fix timeout" --priority High --assignee john.doe

# Sub-task under a parent
orbit -p myprofile jira issue create --project PROJ --type Sub-task \
  --parent PROJ-123 --summary "Add validation"

エピックの作成

エピックには「Epic Name」カスタムフィールドが必要です。--type Epic を指定すると、orbit CLI は概要からこのフィールドを自動設定します。上書きするには --epic-name を使用してください。

# Create an epic (Epic Name auto-set from summary)
orbit -p myprofile jira issue create --type Epic --project PROJ \
  --summary "Q1 Auth Revamp" --priority Highest

# Create epic with Parent Link to a Capability/Initiative
orbit -p myprofile jira issue create --type Epic --project PROJ \
  --summary "Okta Authentication Foundation" \
  --field "customfield_27521=PRT-4378" \
  --priority Highest

--field フラグを使うと、任意のカスタムフィールドを key=value 形式で設定できます。フィールド ID を確認するには jira field list を使用してください。

書式付きの説明で課題を編集する

Jira Server では Markdown ではなく Wiki マークアップを使用します。Jira Cloud では ADF を使用し、プレーンテキストは orbit が自動的に処理します。Server インスタンスでは、--body の値を必ず Wiki マークアップの構文で書式設定してください。

orbit -p myprofile jira issue edit PRT-123 --body "h2. Value Statement

The platform provides real authentication via Okta.

h2. User Stories

* *Story 1:* As a platform admin, I want all API requests to require a valid Okta JWT.
** Okta custom AS configured with epsilon_claims claim
** AUTH_BYPASS removed from all Terraform task definitions"

カスタムフィールド値の編集

-F フラグは複数の値形式に対応しています。正しい形式は Jira のフィールドタイプによって異なります。

# Single-select field — use value: shorthand
orbit -p myprofile jira issue edit PROJ-123 -F customfield_10397=value:Yes

# Multi-select field — MUST use JSON array of objects (value: shorthand will return 400)
orbit -p myprofile jira issue edit PROJ-123 -F 'customfield_10398=[{"value":"Developer"},{"value":"QA"}]'

# Multi-select with a single value still needs array format
orbit -p myprofile jira issue edit PROJ-123 -F 'customfield_10400=[{"value":"Confirmed"}]'

# Number field
orbit -p myprofile jira issue edit PROJ-123 -F customfield_10399=3

# Plain string field
orbit -p myprofile jira issue edit PROJ-123 -F customfield_10010=my-value

重要： 複数選択フィールド（チェックボックス、複数選択ドロップダウン）では、[{"value":"X"}] の配列形式が必要です。複数選択フィールドで value:X を使用すると、400 エラーが返されます。

課題のトランジション

# Move to In Progress
orbit -p myprofile jira issue move PROJ-123 "In Progress"

# Close with comment and resolution
orbit -p myprofile jira issue move PROJ-123 Done --comment "Fixed in v2.1" --resolution Fixed

@メンション付きコメント

issue comment はコメントを書き込みます。コメントを読み取るには、issue view --comments N を使用してください（課題の表示を参照）。

コメントでユーザーに @メンションするには、[~accountId:ID] を使用します（Cloud）。Jira では、これらはクリック可能なユーザーリンクとして表示されます。Server では [~username] を使用してください。

# Add a comment mentioning the assignee
orbit -p myprofile jira issue comment PROJ-123 -b "Hey [~accountId:5b10ac8d82e05b22cc7d4ef5], this needs rework"

# Look up a user's accountId
orbit -p myprofile jira user search "Jorge"

添付ファイル

# Attach a file to an issue
orbit -p myprofile jira issue attach PROJ-123 report.pdf

# Attach multiple files
orbit -p myprofile jira issue attach PROJ-123 screenshot.png log.txt

# List attachments
orbit -p myprofile jira issue attachments PROJ-123

# Download all attachments
orbit -p myprofile jira issue download PROJ-123

# Download only screenshots/images
orbit -p myprofile jira issue download PROJ-123 --images-only --output ./screenshots

# Remove an attachment by ID
orbit -p myprofile jira issue detach 12345

課題の検索

# Filter by project and type
orbit -p myprofile jira issue list --project PROJ --type Epic

# Filter by assignee and status
orbit -p myprofile jira issue list --assignee me --status "In Progress"

# Raw JQL query
orbit -p myprofile jira issue list --jql "project = PROJ AND sprint in openSprints()"

# JSON output for processing
orbit -p myprofile jira issue list --project PROJ -o json

# Fresh list — bypasses the JQL search index (useful right after transitions)
orbit -p myprofile jira issue list --jql "project = PROJ AND status = Open" --fresh

JQL インデックスの遅延 — issue list は Jira の JQL 検索インデックスを使用します。このインデックスは結果整合性で、ステータス遷移が反映されるまで 30～60 秒かかる場合があります。ユーザーが「現在の」「最新の」「リアルタイムの」一覧を求めている場合、または同じセッションでチケットをステータス遷移した直後の場合は、各行を信頼できる単一課題エンドポイントで再検証するため、--fresh を指定してください。--fresh を指定しない場合、一覧の結果は参考情報です。操作を行う前に、必ず jira issue view KEY で単一のキーを再検証してください。

エピック階層のエクスポート

エピック階層全体（エピック → ストーリー → サブタスク）を、構造化された Markdown ディレクトリにエクスポートします。

# Export a single epic
orbit -p myprofile jira export BS-1243 -O ./jira-export

# Export multiple epics
orbit -p myprofile jira export BS-1243 BS-1255 BS-1246 -O ./jira-export

出力構造：

<outdir>/<EPIC-KEY>/INDEX.md                    — epic metadata + story list
<outdir>/<EPIC-KEY>/<STORY-KEY>/INDEX.md        — story metadata + sub-task list
<outdir>/<EPIC-KEY>/<STORY-KEY>/<TASK-KEY>.md   — individual sub-task file

各ファイルには、メタデータテーブル（タイプ、ステータス、担当者、優先度、ラベル、ストーリーポイント）と、Jira ADF から Markdown に変換された説明全文が含まれます。--max-results を使用して、各階層で取得する子課題の数を制御できます（デフォルト：100）。

スプリント管理

# List sprints on a board
orbit -p myprofile jira sprint list --board-id 42
orbit -p myprofile jira sprint list --board-id 42 --state active

# View sprint details
orbit -p myprofile jira sprint view 1366

# List issues in a sprint
orbit -p myprofile jira sprint list 1366

# Create a sprint
orbit -p myprofile jira sprint create --board-id 42 --name "Sprint 5" --start-date 2026-04-01 --end-date 2026-04-15

# Start a sprint
orbit -p myprofile jira sprint start 1366

# Close a sprint
orbit -p myprofile jira sprint close 1366

# Update sprint name/dates/goal
orbit -p myprofile jira sprint update 1366 --name "Sprint 5 Extended" --end-date 2026-04-20

# Add issues to a sprint
orbit -p myprofile jira sprint add 1366 PROJ-101 PROJ-102

# Move issues to backlog
orbit -p myprofile jira sprint remove PROJ-101 PROJ-102

# Delete a sprint
orbit -p myprofile jira sprint delete 1366

ダッシュボードとガジェット

Jira ダッシュボードとガジェットをプログラムから作成、管理します。

# List dashboards
orbit -p myprofile jira dashboard list
orbit -p myprofile jira dashboard list --filter "Sprint"

# Create a dashboard
orbit -p myprofile jira dashboard create --name "AI Metrics" --description "AI adoption tracking"

# View dashboard details
orbit -p myprofile jira dashboard view 10408

# Delete a dashboard
orbit -p myprofile jira dashboard delete 10408

# Add gadgets to a dashboard (use URI format for Cloud)
orbit -p myprofile jira dashboard gadget add 10408 \
  --uri "rest/gadgets/1.0/g/com.atlassian.jira.gadgets:filter-results-gadget/gadgets/filter-results-gadget.xml" \
  --title "My Filter Results" --color blue

# List gadgets on a dashboard
orbit -p myprofile jira dashboard gadget list 10408

# Remove a gadget
orbit -p myprofile jira dashboard gadget remove 10408 35501

# Configure gadget properties (e.g., bind a filter)
orbit -p myprofile jira dashboard gadget property set 10408 35501 config '{"filterId":"11233"}'
orbit -p myprofile jira dashboard gadget property get 10408 35501 config
orbit -p myprofile jira dashboard gadget property list 10408 35501

フィルター

保存済み JQL フィルターを作成、検索、管理します。

# List favourite filters
orbit -p myprofile jira filter list

# Search all accessible filters
orbit -p myprofile jira filter search
orbit -p myprofile jira filter search --name "Sprint"

# View filter details
orbit -p myprofile jira filter view 10195

# Create a filter
orbit -p myprofile jira filter create --name "My Bugs" --jql "project = PROJ AND type = Bug" --favourite

# Update a filter
orbit -p myprofile jira filter update 10195 --jql "project = PROJ AND sprint in openSprints()"
orbit -p myprofile jira filter update 10195 --name "Active Sprint"

# Delete a filter
orbit -p myprofile jira filter delete 12345

フィールド管理（Cloud のみ）

カスタムフィールド、そのコンテキスト、オプションをプログラムから管理します。

フィールドの一覧表示

# List all fields
orbit -p myprofile jira field list

# List only custom fields
orbit -p myprofile jira field list --custom

# Filter by name or ID
orbit -p myprofile jira field list --filter "AI"

カスタムフィールドの作成

# Create a select field (shorthand types: select, multiselect, number, checkbox, text, textarea)
orbit -p myprofile jira field create --name "AI Assisted" --type select \
  --description "Was AI used on this ticket?"

# Create a number field
orbit -p myprofile jira field create --name "AI Prompt Iterations" --type number \
  --description "How many prompt cycles to get working output"

# Create a checkbox field
orbit -p myprofile jira field create --name "Human Review Confirmed" --type checkbox \
  --description "Engineer confirms AI output was reviewed"

フィールドのコンテキストとオプションの管理

# List field contexts
orbit -p myprofile jira field context-list customfield_10397

# List existing options
orbit -p myprofile jira field option-list customfield_10397 10817

# Add options to a select/multiselect field
orbit -p myprofile jira field option-add customfield_10397 10817 \
  --values "Yes,No,Partial"

画面管理

画面タブとフィールドの割り当てを管理して、課題の作成／編集／表示フォームに表示されるフィールドを制御します。

画面とタブの一覧表示

# List all screens
orbit -p myprofile jira screen list

# Filter screens by name
orbit -p myprofile jira screen list --filter "PYMT"

# List tabs on a screen
orbit -p myprofile jira screen tab-list 10089

# List fields on a screen tab
orbit -p myprofile jira screen field-list 10089 10189

タブの作成

# Create a new tab to group related fields
orbit -p myprofile jira screen tab-create 10089 "AI Workflow"

フィールドの追加と削除

# Add fields to a screen tab
orbit -p myprofile jira screen field-add 10089 10868 \
  --fields "customfield_10397,customfield_10398,customfield_10399"

# Remove fields from a screen tab
orbit -p myprofile jira screen field-remove 10089 10189 \
  --fields "customfield_10397,customfield_10398"

タブ間でのフィールドの移動

# Move fields from General tab to AI Workflow tab
orbit -p myprofile jira screen field-move 10089 10189 10868 \
  --fields "customfield_10397,customfield_10398,customfield_10399"

ステータスと課題タイプの管理

ワークフローステータスの一覧表示

# List all statuses with their categories
orbit -p myprofile jira status list

# Filter with grep
orbit -p myprofile jira status list | grep -i "review"

課題タイプの一覧表示

orbit -p myprofile jira issuetype-list

課題の削除

issue delete で課題を削除します。すべてのサブタスクも削除するには、--cascade を使用します。

重要： --confirm フラグも --force フラグもありません。このコマンドは即座に課題を削除します。

# Delete a single issue
orbit -p myprofile jira issue delete PROJ-123

# Delete an issue and all its subtasks
orbit -p myprofile jira issue delete PROJ-100 --cascade

階層（親 → 子 → 孫）の削除： 孤立エラーを避けるには、下位から順に削除するか、サブタスクを持つ各階層で --cascade を使用します。

# Example: delete Story (with sub-tasks) → Epic → Capability
orbit -p myprofile jira issue delete PROJ-50 --cascade   # Story + sub-tasks
orbit -p myprofile jira issue delete PROJ-40              # Epic (now childless)
orbit -p myprofile jira issue delete PRT-200              # Capability (now childless)

ヒント： --cascade が削除するのは Jira のサブタスク（タイプが Sub-task の子課題）だけです。エピック配下のストーリーや、Capability 配下のエピックは削除しません。階層全体を削除するには、まず JQL で子課題を検索し、その後、下位から順に削除してください。

# Find all children of an issue
orbit -p myprofile jira issue list --jql '"Parent" = PROJ-40' -o json

重要な注意事項

• Cloud と Server — Atlassian Cloud ではサービス タイプ jira-cloud を使用してください（API v3 を使用し、説明には ADF を使用します）。Server／Data Center では jira-onprem を使用してください（API v2 を使用し、Wiki マークアップを使用します）。
• 説明の書式設定 — Server インスタンスでは、--body の値に必ず Jira Wiki マークアップを使用してください。Cloud では orbit がプレーンテキストを自動的に ADF に変換します。Wiki マークアップの構文については、references/wiki-markup.md を参照してください。
• フィールド管理 — field create、field context-list、field option-list、field option-add は Cloud 専用の機能です。
• 画面管理 — 画面にフィールドを追加すると、課題の作成／編集フォームに表示されます。関連するフィールドを専用タブにまとめるには、tab-create を使用してください。
• エピックタイプでは --parent フラグを使用できません — エピックはサブタスクタイプではないため、Jira が拒否します。代わりに、--field "customfield_27521=KEY"（Parent Link）を使用してください。
• シークレット参照 - 設定の認証情報では、1Password（op://vault/item/field）または Infisical（infisical://<env>/<path>/<KEY>）の参照を使用できます。これらは実行時に解決されます。orbit auth を一度実行すると、すべてのシークレットが解決され、キャッシュされます（1Password の生体認証プロンプトは 1 回だけ表示されます）。キャッシュを消去するには、orbit auth clear を使用してください。シークレットを参照してください。orbit auth を実行しない場合も、シークレットは各コマンドの実行時に解決されますが、生体認証プロンプトが繰り返し表示されることがあります。