{"_id":"@atlassian-tools/cli","name":"@atlassian-tools/cli","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@atlassian-tools/cli","version":"0.1.1","description":"CLI for Atlassian APIs using GraphQL","main":"./dist/index.js","types":"./dist/index.d.ts","type":"module","exports":{".":"./dist/index.js","./auth/config":"./dist/auth/config.js","./cli":"./dist/cli.js","./jira-cli":"./dist/jira-cli.js","./package.json":"./package.json"},"bin":{"atlassian":"dist/cli.js","jira":"dist/jira-cli.js"},"keywords":["atlassian","jira","confluence","cli","graphql"],"repository":{"type":"git","url":"git+https://github.com/gqlb/gqlb.git","directory":"packages/atlassian-cli"},"homepage":"https://github.com/gqlb/gqlb#readme","bugs":{"url":"https://github.com/gqlb/gqlb/issues"},"license":"MIT","dependencies":{"@atlassian-tools/gql":"*","cli-oauth":"*"},"module":"./dist/index.js","gitHead":"a476368b3df2ecd62d64d9a492e09c700baf39da","_id":"@atlassian-tools/cli@0.1.1","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-P+HFUJLN4Kc2Pj1+Ipr3VDgNQM0myOGgIwa2I95cXX3/3/aK46vCA1F7aI+AJqdPyhefyb37YDdbWKzpfIIM1w==","shasum":"6d872947a68b1bca844d37f9a3d5da02e766e5e8","tarball":"https://registry.npmjs.org/@atlassian-tools/cli/-/cli-0.1.1.tgz","fileCount":50,"unpackedSize":5405545,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCbNeR9LDWjpt8kI8u0Pw8Z5OPPhxVgapPTBNJDYgUBpAIgSq70tDVVJy2tqOfDgbN5XXtMycQ2aRDFzqm8p1skAx0="}]},"_npmUser":{"name":"theplenkov-npm","email":"petr.plenkov@gmail.com"},"directories":{},"maintainers":[{"name":"theplenkov-npm","email":"petr.plenkov@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cli_0.1.1_1761910298494_0.6475739077811689"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-31T11:31:38.383Z","0.1.1":"2025-10-31T11:31:38.742Z","modified":"2025-10-31T11:31:39.093Z"},"maintainers":[{"name":"theplenkov-npm","email":"petr.plenkov@gmail.com"}],"description":"CLI for Atlassian APIs using GraphQL","homepage":"https://github.com/gqlb/gqlb#readme","keywords":["atlassian","jira","confluence","cli","graphql"],"repository":{"type":"git","url":"git+https://github.com/gqlb/gqlb.git","directory":"packages/atlassian-cli"},"bugs":{"url":"https://github.com/gqlb/gqlb/issues"},"license":"MIT","readme":"# @atlassian-tools/cli\n\n> 🎯 **Demo Application:** This CLI demonstrates real-world usage of [`gqlb`](../gqlb) with dynamic field selection, OAuth authentication, and interactive commands. It serves as a reference implementation and will be moved to its own repository soon.\n\n**Command-line interface for Atlassian APIs powered by gqlb**\n\nAn interactive CLI showcasing [`gqlb`](../gqlb)'s capabilities: dynamic field selection, runtime query building, and full type safety with Atlassian's GraphQL API (8000+ types).\n\n## Architecture\n\n```\n@atlassian-tools/cli    (Demo: CLI commands & OAuth)\n    ↓\n@atlassian-tools/gql    (Demo: Pre-configured gqlb for Atlassian)\n    ↓\ngqlb                    (Core: Runtime query builder)\n```\n\n## 📚 About This Package\n\nThis is a **demonstration of gqlb in a real application**. It shows:\n\n- Dynamic field selection at runtime\n- OAuth 2.0 authentication flow\n- Building complex queries with gqlb\n- Interactive CLI with full type safety\n- Working with a massive schema (8000+ types)\n\n**Looking for the core library?** Check out [`gqlb`](../gqlb) - it works with any GraphQL API, not just Atlassian.\n\n## Installation\n\n```bash\nnpm install -g @atlassian-tools/cli\n```\n\nOr use directly from the workspace:\n\n```bash\ncd packages/atlassian-cli\nnpm install\nnpx nx build atlassian-cli\n```\n\n## Authentication\n\nThe CLI stores configuration in `~/.atlassian-tools/`:\n- `config.json` - OAuth client credentials and cloud ID\n- `token.json` - Access and refresh tokens\n\n### Option 1: OAuth Flow (Recommended)\n\n1. **Create an OAuth 2.0 App** at [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)\n   - Click \"Create\" → \"OAuth 2.0 integration\"\n   - Name your app (e.g., \"My Atlassian CLI\")\n   - Add redirect URI: `http://localhost:3000/callback`\n   - Set permissions:\n     - Jira API: `read:jira-work`, `write:jira-work`, `read:jira-user`\n     - Confluence API: `read:confluence-content.all`\n     - Offline access: `offline_access` (for token refresh)\n   - Copy your Client ID and Client Secret\n\n2. **Login via OAuth**:\n```bash\natlassian login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET\n```\n\nThis will:\n- Open your browser for authorization\n- Exchange the code for an access token\n- Fetch and save your Cloud IDs\n- Store credentials securely\n\n### Option 2: API Token (Quick Start)\n\nGenerate an API token at [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)\n\n```bash\natlassian login --token YOUR_API_TOKEN\n```\n\n### Check Authentication Status\n\n```bash\natlassian whoami\n```\n\nShows:\n- Config file locations\n- Token status and expiration\n- Cloud IDs\n- User info (if valid)\n\n### Logout\n\n```bash\natlassian logout\n```\n\n## Usage Examples\n\nOnce logged in, you can use the CLI without specifying tokens or cloud IDs.\n\n### Jira Commands\n\n#### Get Issue\n\n```bash\n# Basic fetch\natlassian jira get PROJ-123\n\n# Specific fields\natlassian jira get PROJ-123 --fields id,key,issueId,webUrl\n\n# Nested fields (dot notation)\natlassian jira get PROJ-123 --fields id,key,summaryField.text,assigneeField.user.name\n\n# JSON output (great for scripting!)\natlassian jira get PROJ-123 --json | jq '.jira.issue.summaryField.text'\n```\n\n#### Search Issues\n\n```bash\n# Basic search\natlassian jira search \"project = DEMO\"\n\n# With specific fields\natlassian jira search \"project = DEMO\" --fields id,key,webUrl --limit 20\n\n# Complex JQL with nested fields\natlassian jira search \"assignee = currentUser() AND status = Open\" \\\n  --fields id,key,summaryField.text,statusField.name\n\n# JSON output for scripting\natlassian jira search \"project = DEMO\" --json | jq '.jira.issueSearch.edges[].node.key'\n```\n\n### Development Mode\n\nRun directly without building:\n\n```bash\n# From packages/atlassian-cli\nnpx tsx src/cli.ts login --token YOUR_TOKEN\nnpx tsx src/cli.ts whoami\nnpx tsx src/cli.ts jira get PROJ-123 --fields id,key,webUrl\n```\n\n## Features\n\n✅ **Dynamic field selection** - Choose fields at runtime (powered by gqlb)\n✅ **Nested fields** - Use dot notation for nested data  \n✅ **Type-safe** - Full TypeScript autocomplete via gqlb  \n✅ **Beautiful output** - Formatted GraphQL queries and JSON results  \n✅ **OAuth + Token auth** - Production-ready authentication  \n✅ **Stored credentials** - Login once, use everywhere  \n✅ **JSON output** - Perfect for scripting with `jq`\n✅ **Multiple commands** - Jira, Confluence (coming soon)  \n\n## How It Works\n\nThis CLI demonstrates **gqlb's dynamic query building**:\n\n1. **Parse command** - Extract issue key, fields, options\n2. **Build query** - Use gqlb to create query at runtime\n3. **Execute** - Send to Atlassian GraphQL API\n4. **Display** - Format and show results\n\n**The magic:** gqlb uses runtime proxies to walk the GraphQL schema on-the-fly, generating queries with full type safety and zero code generation!\n\nExample from the code:\n\n```typescript\n// src/commands/jira/get.ts\nimport { createQueryBuilder, $$ } from '@atlassian-tools/gql';\n\nconst builder = createQueryBuilder();\nconst issueIdOrKey = $$<string>('issueIdOrKey');\n\n// Dynamic query based on user's --fields option\nconst query = builder.query('GetIssue', q => [\n  q.jira(jira => [\n    jira.issueByKeyOrId({ issueIdOrKey }, issue => [\n      // Fields selected by user at runtime!\n      ...buildFieldsFromUserInput(issue, fields)\n    ])\n  ])\n]);\n```\n\n## Sample Output\n\n```bash\n$ atlassian jira get PROJ-123 --fields id,key,summaryField.text\n\n🔍 Fetching issue: PROJ-123\n📋 Fields: id, key, summaryField.text\n\n📝 Generated GraphQL Query:\n────────────────────────────────────────────────────────────\nquery GetIssue($issueIdOrKey: String!) {\n  jira {\n    issueByKeyOrId(issueIdOrKey: $issueIdOrKey) {\n      id\n      key\n      summaryField {\n        text\n      }\n    }\n  }\n}\n────────────────────────────────────────────────────────────\n\n🚀 Executing query...\n\n✅ Result:\n{\n  \"jira\": {\n    \"issueByKeyOrId\": {\n      \"id\": \"10042\",\n      \"key\": \"PROJ-123\",\n      \"summaryField\": {\n        \"text\": \"Fix authentication bug\"\n      }\n    }\n  }\n}\n```\n\n## Use This as a Template\n\nWant to build a CLI for your own GraphQL API? This package is a great starting point:\n\n1. Replace `@atlassian-tools/gql` with your own gqlb instance\n2. Update commands to match your schema\n3. Customize authentication\n4. Add your specific commands\n\nSee the [`gqlb` documentation](../gqlb) for details on using gqlb with any GraphQL API.\n\n## Contributing\n\nAdd new commands in `src/commands/`:\n\n```typescript\n// src/commands/jira/my-command.ts\nimport { createQueryBuilder, $$ } from '@atlassian-tools/gql';\n\nexport async function myCommand(arg: string, options: MyOptions) {\n  const builder = createQueryBuilder();\n  const myVar = $$<string>('myVar');\n  \n  const query = builder.query('MyQuery', q => [\n    q.jira(jira => [\n      // Your query here using gqlb!\n    ])\n  ]);\n  \n  // Execute and display results\n}\n```\n\nThen register in `src/cli.ts`:\n\n```typescript\nimport { myCommand } from './commands/jira/my-command';\n\njira\n  .command('my-command <arg>')\n  .description('My new command')\n  .action(myCommand);\n```\n\n## 🎯 Why This Demo?\n\nThis CLI shows gqlb handling real-world challenges:\n\n- **Complex schema** - 8000+ Atlassian types\n- **Deep nesting** - 10+ levels of nested objects\n- **Dynamic queries** - User chooses fields at runtime\n- **Production auth** - OAuth 2.0 with token refresh\n- **Great UX** - Beautiful output, error handling\n\nAll with:\n- ✅ Full type safety\n- ✅ Instant autocomplete\n- ✅ Tiny bundle size\n- ✅ Zero code generation\n\n## 🔗 Related\n\n- **[gqlb](../gqlb)** - The core library (works with any GraphQL API)\n- **[@atlassian-tools/gql](../atlassian-graphql)** - Pre-configured gqlb for Atlassian\n- **[Innovation Deep Dive](../../docs/INNOVATION.md)** - How gqlb works\n\n## Environment Variables (Optional)\n\nOverride stored config with environment variables:\n\n```bash\nexport ATLASSIAN_TOKEN=\"your-api-token\"\nexport ATLASSIAN_CLOUD_ID=\"your-cloud-id\"\nexport ATLASSIAN_API_URL=\"https://api.atlassian.com/graphql\"\n\natlassian jira get PROJ-123\n```\n\n## 📄 License\n\nMIT\n\n---\n\n**This is a demo/reference implementation. For the core library, see [`gqlb`](../gqlb).**\n","readmeFilename":"README.md","_rev":"1-a0c783977d74c7838e9dfba822fc1245"}