{
  "title": "راهنمای ابزار خط فرمان (Nons CLI)",
  "slug": "team/platform/package/cli-reference",
  "url": "/docs/team/platform/package/cli-reference",
  "frontmatter": {
    "layout": "doc",
    "title": "راهنمای ابزار خط فرمان (Nons CLI)",
    "description": "مستند فنی و راهنمای کاربری ابزار CLI خط فرمان پلتفرم NONS",
    "version": "2.2.0",
    "status": "APPROVED",
    "author": "Platform Team",
    "owner": "Platform Team",
    "created_at": "2026-07-01",
    "updated_at": "2026-07-04",
    "tags": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "راهنمای ابزار خط فرمان (Nons CLI)",
      "content": "**Platform CLI** — تنها ابزار رسمی توسعه‌دهنده برای تعامل با سرویس‌های پلتفرم NONS.\n\n> **مسئولیت CLI:** مدیریت قراردادها، رجیستری، باندل‌ها و تولید مصنوعات پروژه. CLI یک ابزار Contract Management است که کدهای مصرف‌کننده را برای فریم‌ورک هدف تولید می‌کند.\n\n> **وضعیت:** این سند معماری کلی CLI و حوزه‌های مسئولیتی آن را شرح می‌دهد. دستورات دقیق و پرچم‌ها در فاز پیاده‌سازی نهایی می‌شوند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. فلسفه معماری",
      "content": "```\nCLI یک ابزار ایستا (Build-time) است، نه یک کتابخانه زمان اجرا (Runtime).\n```\n\n| ویژگی | توضیح |\n|--------|--------|\n| **مستقل** | یک فایل اجرایی واحد — بدون وابستگی به Node.js یا runtime دیگر |\n| **چندسکویی** | Windows, macOS, Linux |\n| **زبان‌آگنوستیک** | پروژه مصرف‌کننده می‌تواند هر زبانی داشته باشد |\n| **خروجی پروژه‌محور** | کدها متناسب با فریم‌ورک هدف تولید می‌شوند |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. نصب",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "دانلود آخرین نسخه",
      "content": "curl -fsSL https://nons.dev/cli/install.sh | sh"
    },
    {
      "level": 1,
      "heading": "یا دانلود مستقیم از GitHub Releases",
      "content": ""
    },
    {
      "level": 1,
      "heading": "https://github.com/nons-dev/cli/releases",
      "content": "```\n\nCLI به صورت یک باینری مستقل توزیع می‌شود — نیاز به Node.js، npm، pnpm یا هیچ وابستگی دیگری ندارد.\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. دستورات رسمی",
      "content": ""
    },
    {
      "level": 3,
      "heading": "`nons init`",
      "content": "مقداردهی اولیه پروژه کلاینت. یک ویزارد تعاملی برای انتخاب فریم‌ورک پروژه اجرا می‌کند.\n\n```bash\nnons init\n```\n\n**خروجی:** ایجاد دایرکتوری `.nons/` با ساختار اولیه و فایل `config.yaml`.\n\n---"
    },
    {
      "level": 3,
      "heading": "`nons registry build <service>`",
      "content": "ساخت Service Manifest از OpenAPI یک سرویس.\n\n```bash\nnons registry build user --source services/user-service/docs/openapi.yaml\n```\n\n**خروجی:** `.nons/registry/user/manifest.json`\n\n```bash\nnons registry build user --update   # بروزرسانی رجیستری موجود\n```\n\n---"
    },
    {
      "level": 3,
      "heading": "`nons registry list`",
      "content": "فهرست تمام رجیستری‌های محلی.\n\n```bash\nnons registry list\n```\n\n**خروجی:** نام سرویس، نسخه، تعداد operationها، تاریخ آخرین بروزرسانی.\n\n---"
    },
    {
      "level": 3,
      "heading": "`nons bundle create`",
      "content": "ساخت باندل از مجموعه‌ای از سرویس‌ها.\n\n```bash\nnons bundle create --name my-app --services user,auth\n```\n\n**خروجی:** `.nons/bundles/my-app/bundle.json`\n\n```bash\nnons bundle list                # لیست باندل‌ها\nnons bundle inspect my-app      # جزئیات باندل\nnons bundle update my-app       # بروزرسانی باندل\nnons bundle delete my-app       # حذف باندل\n```\n\n---"
    },
    {
      "level": 3,
      "heading": "`nons generate`",
      "content": "تولید مصنوعات پروژه بر اساس رجیستری‌ها و باندل‌های محلی.\n\n```bash\nnons generate\n```\n\nCLI فریم‌ورک هدف را از `config.yaml` می‌خواند و مصنوعات مناسب را در `.nons/generated/` تولید می‌کند.\n\n**خروجی بر اساس فریم‌ورک:**\n\n| فریم‌ورک | مسیر خروجی | مصنوعات |\n|----------|-----------|---------|\n| React / Next.js | `.nons/generated/hooks/` | Custom Hooks, Types, API Client |\n| Vue / Nuxt | `.nons/generated/composables/` | Composables, Types, API Client |\n| Flutter | `.nons/generated/dart/` | Dart Classes, API Service |\n| React Native | `.nons/generated/hooks/` | Custom Hooks, Types |\n\n---"
    },
    {
      "level": 3,
      "heading": "`nons validate`",
      "content": "اعتبارسنجی قراردادها، رجیستری‌ها و باندل‌ها.\n\n```bash\nnons validate               # بررسی همه\nnons validate --registry    # فقط رجیستری\nnons validate --bundle      # فقط باندل\nnons validate --endpoints   # سلامت اندپوینت‌ها\n```\n\n---"
    },
    {
      "level": 3,
      "heading": "`nons interactive` / `nons ui`",
      "content": "حالت تعاملی (TUI) برای مرور سرویس‌ها، ساخت باندل و تولید مصنوعات.\n\n```bash\nnons interactive\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. ساختار دایرکتوری `.nons/`",
      "content": "```\nproject/\n└── .nons/\n    ├── config.yaml              # تنظیمات پروژه (فریم‌ورک، مسیرها)\n    │\n    ├── registry/                # ← تولیدشده توسط nons registry build\n    │   ├── user/\n    │   │   └── manifest.json\n    │   └── auth/\n    │       └── manifest.json\n    │\n    ├── bundles/                 # ← تولیدشده توسط nons bundle create\n    │   └── my-app/\n    │       └── bundle.json\n    │\n    └── generated/               # ← تولیدشده توسط nons generate\n        ├── types/\n        ├── api-client/\n        └── hooks/               # (واکنش‌گرا: React Hooks, Vue Composables, ...)\n```\n\n**قوانین طلایی:**\n\n1. هیچ فایلی در `.nons/` دستی ویرایش نمی‌شود — به جز `config.yaml`\n2. `registry/` فقط توسط `nons registry build` مدیریت می‌شود\n3. `bundles/` فقط توسط `nons bundle` مدیریت می‌شود\n4. `generated/` فقط توسط `nons generate` تولید می‌شود\n5. `.nons/` در git commit می‌شود\n6. `generated/` در `.gitignore` نیست — اعضای تیم پس از clone باید `nons generate` را اجرا کنند\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. پیکربندی Transport در `config.yaml`",
      "content": "پیکربندی transport به `config.yaml` اضافه شده تا جنریتور بتواند به جای مقادیر hardcodeشده از config مصرف‌کننده استفاده کند. این توسط [ADR-Platform-005](../ADR/ADR-Platform-005) مصوب شد.\n\n```yaml\nproject:\n  name: my-app\n  framework: react    # react | vue | next | nuxt | angular | svelte | node\n  version: 1.0.0\n\npaths:\n  registry: .nons/registry\n  bundles: .nons/bundles\n  output: .nons/generated\n\ntransport:                               # اختیاری — پیش‌فرض بر اساس framework انتخاب می‌شود\n  base_url_env: REACT_APP_API_URL        # نام env var فریم‌ورک\n  credentials: omit                      # include | omit | same-origin\n  default_timeout: 10000                 # ms\n```\n\n**پیش‌فرض‌های فریم‌ورکی (اگر `transport` تعریف نشده باشد):**\n\n| فریم‌ورک | `base_url_env` | `credentials` |\n|---------|--------------|---------------|\n| `next` | `NEXT_PUBLIC_API_URL` | `include` |\n| `react` | `REACT_APP_API_URL` | `omit` |\n| `vue` | `VITE_API_URL` | `omit` |\n| `nuxt` | `NUXT_PUBLIC_API_URL` | `include` |\n| `angular` | `API_URL` | `omit` |\n| `svelte` | `VITE_API_URL` | `omit` |\n| `node` | `API_URL` | `omit` |\n\n> **توضیح:** `credentials: include` برای حالتی است که سرویس از cookie-based auth استفاده می‌کند (cross-origin CORS با `Access-Control-Allow-Credentials: true`). برای سرویس‌های با احراز هویت Bearer-only مقدار `omit` امن‌تر است.\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. مصنوعات تولیدشده — مثال (React/Next.js)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "types/user.ts",
      "content": "```typescript\n// .nons/generated/types/user.ts\n// ★ GENERATED BY nons generate — DO NOT EDIT ★\n\nexport interface UserResponse {\n  id: string;\n  displayName: string;\n  avatar: string | null;\n  createdAt: string;\n}\n\nexport interface ListUsersRequest {\n  limit?: number;\n  cursor?: string;\n}\n\nexport interface ListUsersResponse {\n  success: boolean;\n  data: UserResponse[];\n  meta: { pagination: { next_cursor: string | null; has_more: boolean; limit: number } };\n}\n```"
    },
    {
      "level": 3,
      "heading": "api-client/user.ts",
      "content": "```typescript\n// .nons/generated/api-client/user.ts\n// ★ GENERATED BY nons generate — DO NOT EDIT ★\n\nimport type { ListUsersRequest, ListUsersResponse, UserResponse } from '../types/user';\n\nconst BASE_URL = process.env.NEXT_PUBLIC_API_URL;\n\nexport async function listUsers(data: ListUsersRequest): Promise<ListUsersResponse> {\n  const params = new URLSearchParams();\n  if (data.limit) params.set('limit', String(data.limit));\n  if (data.cursor) params.set('cursor', data.cursor);\n  const res = await fetch(`${BASE_URL}/v1/users?${params}`, {\n    headers: { Authorization: `Bearer ${getToken()}` },\n  });\n  if (!res.ok) throw new ApiError(await res.json());\n  return res.json();\n}\n\nexport async function getUser(id: string): Promise<UserResponse> {\n  const res = await fetch(`${BASE_URL}/v1/users/${id}`, {\n    headers: { Authorization: `Bearer ${getToken()}` },\n  });\n  if (!res.ok) throw new ApiError(await res.json());\n  return res.json();\n}\n```"
    },
    {
      "level": 3,
      "heading": "hooks/useUsers.ts (React)",
      "content": "```typescript\n// .nons/generated/hooks/useUsers.ts\n// ★ GENERATED BY nons generate — DO NOT EDIT ★\n\nimport { useState, useEffect } from 'react';\nimport { listUsers } from '../api-client/user';\nimport type { UserResponse } from '../types/user';\n\nexport function useUsers(limit = 20) {\n  const [users, setUsers] = useState<UserResponse[]>([]);\n  const [loading, setLoading] = useState(true);\n\n  useEffect(() => {\n    listUsers({ limit }).then(res => {\n      setUsers(res.data);\n      setLoading(false);\n    });\n  }, [limit]);\n\n  return { users, loading };\n}\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. جریان کاری کامل",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "1. مقداردهی اولیه پروژه",
      "content": "nons init"
    },
    {
      "level": 1,
      "heading": "→ ویزارد تعاملی: انتخاب فریم‌ورک (Next.js)",
      "content": ""
    },
    {
      "level": 1,
      "heading": "→ ایجاد .nons/config.yaml",
      "content": ""
    },
    {
      "level": 1,
      "heading": "2. ساخت رجیستری از OpenAPI سرویس",
      "content": "nons registry build user --source services/user-service/docs/openapi.yaml"
    },
    {
      "level": 1,
      "heading": "→ ایجاد .nons/registry/user/manifest.json",
      "content": ""
    },
    {
      "level": 1,
      "heading": "3. ساخت باندل",
      "content": "nons bundle create --name my-app --services user"
    },
    {
      "level": 1,
      "heading": "→ ایجاد .nons/bundles/my-app/bundle.json",
      "content": ""
    },
    {
      "level": 1,
      "heading": "4. تولید مصنوعات پروژه",
      "content": "nons generate"
    },
    {
      "level": 1,
      "heading": "→ ایجاد .nons/generated/types/",
      "content": ""
    },
    {
      "level": 1,
      "heading": "→ ایجاد .nons/generated/api-client/",
      "content": ""
    },
    {
      "level": 1,
      "heading": "→ ایجاد .nons/generated/hooks/",
      "content": ""
    },
    {
      "level": 1,
      "heading": "5. اعتبارسنجی",
      "content": "nons validate\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. تغییر اندپوینت در بک‌اند",
      "content": "هنگامی که بک‌اند یک اندپوینت را تغییر می‌دهد:\n\n```bash"
    },
    {
      "level": 1,
      "heading": "مرحله ۱: بروزرسانی رجیستری",
      "content": "nons registry build user --update"
    },
    {
      "level": 1,
      "heading": "مرحله ۲: بازتولید مصنوعات",
      "content": "nons generate\n```\n\n**در هیچکدام از این مراحل، کد پروژه کلاینت تغییر نمی‌کند.**\n\n---"
    },
    {
      "level": 2,
      "heading": "۸. یکپارچگی با Platform Contracts (Proto + Buf)",
      "content": "CLI به صورت مستقیم از Bindingهای TypeScript تولیدشده توسط Buf استفاده نمی‌کند. جریان یکپارچگی:\n\n```\nnons-api/contracts/*.proto\n       │\n       ▼ [buf generate]\nPlatform TypeScript Bindings\n       │\n       ▼ [استفاده در CLI Generator]\nمتدهای تولیدشده در API Client\n```\n\nPlatform Types (Error Envelope, ...) در زمان تولید توسط CLI به کدهای خروجی تزریق می‌شوند.\n\n---"
    },
    {
      "level": 2,
      "heading": "مستندات مرتبط",
      "content": "| سند | توضیح |\n|-----|--------|\n| [ADR-Platform-004](../ADR/ADR-Platform-004) | تصمیمات معماری CLI و Registry |\n| [ADR-Platform-005](../ADR/ADR-Platform-005) | معماری Generator Metadata و Template-per-Framework |\n| [OpenAPI Guidelines](../api/openapi-guidelines) | استاندارد تولید OpenAPI |\n| [Repository Structure](../standards/repository-structure) | مسیر فایل‌ها در سرویس |"
    }
  ]
}