giraffy-cli

name	giraffy-cli
description	Use the installed `giraffy` CLI to collect Jira/Confluence issue context into a local LLM-ready bundle and inspect output graph/artifacts. Trigger when a user asks to gather context for a Jira key, run `giraffy collect`, initialize or validate config, verify PATH installation, troubleshoot collection failures, or summarize generated `~/.giraffy/ISSUE_KEY/` results.

Giraffy CLI

Overview

Use this skill to run giraffy end-to-end on the local machine: install or verify binary access, initialize config, collect issue context, and summarize generated artifacts for downstream agent work.

Quick Workflow

1. Verify installation and version.
2. Initialize and validate config.
3. Run a fast collection (--no-attachments) to confirm connectivity.
4. Run a full collection (with attachments) when needed.
5. Inspect and summarize run_manifest.json, graph.json, llm_context.md, and warnings.

1) Verify Installation

Run:

command -v giraffy
giraffy version

If not found in PATH and you are in the giraffy source repo, run:

make install

If needed, install to a specific directory:

make install INSTALL_DIR=/usr/local/bin

2) Initialize and Validate Config

Use default config path (~/.giraffy/config.json) unless the user requested a custom path.

giraffy init
giraffy config validate

If validation fails, inspect and fix:

• binaries.jiraBin
• binaries.confluenceBin (required only when confluence.enabled=true)
• execution.commandTimeoutSec
• traversal.maxIssues
• attachments.maxBytes

3) Collect Context

Use a timestamped temporary output root when smoke-testing.

Fast smoke test:

out="/tmp/giraffy-smoke-$(date +%s)"
mkdir -p "$out"
giraffy collect PROJ-123 --output "$out" --no-attachments --verbose

Full run:

out="/tmp/giraffy-full-$(date +%s)"
mkdir -p "$out"
giraffy collect PROJ-123 --output "$out" --verbose

Use extra flags only when requested:

• --include-raw
• --max-attachment-bytes <n>
• --config <path>

4) Inspect Output Bundle

Given OUT=/path/to/output/ISSUE_KEY, inspect:

jq . "$OUT/run_manifest.json"
jq -r '"nodes=\(.nodes|length) edges=\(.edges|length)"' "$OUT/graph.json"
sed -n '1,160p' "$OUT/llm_context.md"
find "$OUT" -maxdepth 4 -type f | sort

Priority checks:

• issueCount, linkedCount, parentCount, descendantCount
• attachment download stats
• warningsCount and warnings.log
• expected issue folders under jira/issues/
• expected Confluence outputs under confluence/pages/ (when links exist)

5) Troubleshoot Quickly

• Jira preflight failure (jira me): verify Jira CLI auth/session.
• Confluence preflight failure (confluence spaces): verify Confluence CLI auth/session.
• Empty or partial graph: verify issue key correctness and Jira access scope.
• Missing attachments: check --no-attachments, size limit, and warnings.
• Missing Confluence exports: confirm links exist in collected issue text/comments and check warnings.
• PATH problems: verify install location and shell profile exports.

Output Summary Pattern

When reporting results to the user, include:

1. Exact command run.
2. Output directory path.
3. Core manifest metrics.
4. Whether attachments and Confluence pages were exported.
5. Any warnings/errors and next corrective step.

Guardrails

• Prefer non-destructive testing in /tmp unless user asked for a persistent location.
• Avoid printing secrets from environment/config in the response.
• Keep logs concise; surface only actionable lines.
• Preserve user-specified config/flags exactly when they are intentional.