# سقف مصرف

> ccam usage سقف ۵ ساعته و هفتگی همه حساب‌ها را یک‌جا نشان می‌دهد و ccam statusline نام حساب و مصرف آن را در Claude Code نمایش می‌دهد.

Source: https://ccam.dev/fa/features/usage/ · Updated 2026-10-19

`ccam usage` نشان می‌دهد هر حساب چه مقدار از سقف ۵ ساعته و هفتگی خود را مصرف کرده است، همراه با زمان باقی‌مانده تا بازنشانی هر پنجره. پیش از شروع یک کار طولانی، یا وقتی Claude Code به شما می‌گوید به سقف نزدیک شده‌اید، از آن استفاده کنید تا ببینید کدام حساب هنوز ظرفیت دارد. `ccam statusline` فرمان خط وضعیت برای Claude Code است: نام حساب و مصرف آن را داخل Claude Code نشان می‌دهد و عددها را برای `ccam usage` ذخیره می‌کند.

## استفاده

```sh
ccam usage                  # every account, once
ccam u                      # the same, shorter
ccam usage --watch          # redraw every 60 seconds until Ctrl+C
ccam usage --watch=10       # redraw every 10 seconds
ccam usage -v               # add per-model weekly limits and the data source
ccam usage --json           # machine-readable, one object per account
ccam usage --source cache   # saved numbers only, no network
ccam usage --refresh        # also renew expired logins of accounts not running
ccam statusline install     # set the status line in every account's settings.json
```

```console
$ ccam usage
 Account     5-hour        Resets    Weekly        Resets    As of
 1 personal  ░░░░░░░░   0% -         ██████░░  70% 2d 16h    9h 36m ago (cached)
 2 work      ██░░░░░░  24% 2h 29m    ███░░░░░  41% 3d 11h    just now (cached)
 3 side      login expired, run `ccam side` once to refresh
→ Most headroom: personal   (open it with ccam next --auto)
```

در ترمینال، جدول بلافاصله با `fetching…` در هر ردیف نمایش داده می‌شود و هر ردیف به محض پاسخ دادن حساب آن دوباره رسم می‌شود. `As of` نشان می‌دهد عددها چقدر قدیمی‌اند؛ `(cached)` یعنی عددها از یک فایل ذخیره‌شده آمده‌اند، نه از نقطه پایانی. خط آخر حسابی را نام می‌برد که کمترین مصرف ۵ ساعته زیر ۱۰۰٪ را دارد و فقط وقتی نمایش داده می‌شود که بیش از یک حساب داشته باشید. حسابی که وارد نشده است `not logged in → ccam login <name>` را نشان می‌دهد و حساب کلید API پیام `no limits (API)` را.

پس از `ccam statusline install`، Claude Code خطی مانند `[work] · Opus · 5h 24% · 7d 41%` را نشان می‌دهد.

## گزینه‌ها

| گزینه | کاری که انجام می‌دهد | پیش‌فرض |
| --- | --- | --- |
| `--json` | گزارش‌ها را به‌صورت JSON چاپ می‌کند: `name`، `slot`، `status`، `limits`، `source`، `at`، `error` | خاموش |
| `--watch[=N]` | هر `N` ثانیه دوباره رسم می‌کند تا Ctrl+C را بزنید. `--watch` به‌تنهایی، یا مقدار ۰ یا کمتر، یعنی ۶۰ | خاموش |
| `-v`، `--verbose` | سقف‌های هفتگی ویژه هر مدل و یک خط `source:` (`live`، `cache` یا `statusline`) را نشان می‌دهد | خاموش |
| `--no-cache` | حافظه نهان ۶۰ ثانیه‌ای را نادیده می‌گیرد و دوباره از نقطه پایانی می‌پرسد | خاموش |
| `--source live\|cache` | `cache` هرگز از نقطه پایانی نمی‌پرسد و فقط عددهای ذخیره‌شده را نشان می‌دهد؛ `live` رفتار پیش‌فرض است | live |
| `--refresh` | توکن‌های دسترسی منقضی‌شده را تمدید می‌کند، فقط برای حساب‌هایی که در حال اجرا نیستند | خاموش |
| `--dry-run` | پذیرفته می‌شود: `ccam usage` به جز حافظه نهان خودش چیزی را تغییر نمی‌دهد. همراه با `--refresh` رد می‌شود: `--dry-run cannot be combined with --refresh, which rewrites login tokens` | خاموش |

هر مقدار دیگری برای `--source` با `--source must be live or cache` خطا می‌دهد. `ccam usage` هیچ آرگومانی نمی‌گیرد.

`ccam statusline` JSON خط وضعیت Claude Code را از ورودی استاندارد می‌خواند. تنها گزینه آن `--wrap <command>` است: یک فرمان خط وضعیت موجود که نام حساب پیش از نخستین خط خروجی آن قرار می‌گیرد. `ccam statusline install` هیچ گزینه‌ای نمی‌گیرد. هر دو `--dry-run` را با `` --dry-run is not supported by `ccam statusline`; nothing was changed `` رد می‌کنند.

## چگونه کار می‌کند

عددها از دو جا می‌آیند: نقطه پایانی مصرف Anthropic که مستند نشده است، یعنی `GET https://api.anthropic.com/api/oauth/usage`، که با ورود خود هر حساب فراخوانی می‌شود، و مقدارهایی که Claude Code به فرمان خط وضعیت خود می‌دهد. همه این‌ها در `internal/usage` قرار دارد.

1. `cli.usageCmd` فایل `config.toml` را بارگذاری می‌کند و برای هر حساب یک `usage.Account` می‌سازد: پوشه آن `~/.local/share/ccam/profiles/<name>/`، پوشه نشست آن (برای اینکه ببیند در حال اجراست یا نه) و اینکه آیا در همان محل وارد شده است.
2. `Fetcher.FetchAll` برای هر حساب یک goroutine آغاز می‌کند. همه آن‌ها یک `http.Client` مشترک دارند، بنابراین اتصال‌ها به نقطه پایانی دوباره استفاده می‌شوند. برقراری اتصال می‌تواند ۲ ثانیه طول بکشد و هر حساب روی هم ۳ ثانیه فرصت دارد. کلاینت هدایت‌ها را دنبال نمی‌کند، چون یک هدایت توکن را به جای دیگری می‌فرستد، و حداکثر ۱ MB از پاسخ را می‌خواند.
3. با تمام شدن کار هر حساب، ردیف آن دوباره رسم می‌شود. حسابی که ناموفق باشد یا به‌موقع پاسخ ندهد به عددهای ذخیره‌شده برمی‌گردد، بنابراین یک حساب کند هرگز بقیه را معطل نمی‌کند.

هر حساب در goroutine خودش با نقطه پایانی کار می‌کند؛ حسابی که مهلتش تمام شود به‌جای آن عددهای ذخیره‌شده خود را نشان می‌دهد.

`personal` و `work` به‌موقع پاسخ می‌دهند و عددهای زنده را نشان می‌دهند. `side` بیش از ۳ ثانیه طول می‌کشد، پس `fallback()` دو فایل حافظه نهان آن را می‌خواند و از هر کدام که آخر نوشته شده استفاده می‌کند. `usage.Table()` ردیف‌ها را رسم می‌کند و `usage.Best()` حسابی را که در خط آخر نام برده می‌شود انتخاب می‌کند.

برای یک حساب، `Fetcher.Fetch` این بررسی‌ها را به ترتیب انجام می‌دهد:

1. با `--source cache`، مستقیم به `fallback()` می‌رود.
2. مگر اینکه `--no-cache` تنظیم شده باشد، یک نتیجه زنده در `~/.local/state/ccam/usage/<name>.json` که کمتر از ۶۰ ثانیه (`CacheTTL`) از آن گذشته باشد همان‌طور که هست برگردانده می‌شود. اجرای دو بار پشت سر هم `ccam usage` برای هر حساب فقط یک درخواست هزینه دارد.
3. `readCredentials()` فایل `.credentials.json` (یا Keychain سیستم macOS) را بدون تغییر می‌خواند و فقط کلید `claudeAiOauth` رمزگشایی می‌شود. نبودن ورود اشتراکی یعنی `not logged in`، یا `no limits (API)` وقتی `.claude.json` یک کلید API دارد.
4. توکن دسترسی منقضی‌شده استفاده نمی‌شود. بدون `--refresh`، حساب عددهای ذخیره‌شده خود را با علامت منقضی‌شده نشان می‌دهد.
5. در غیر این صورت ccam نقطه پایانی را فراخوانی می‌کند. پاسخ 401 یا 403 به‌عنوان ورود منقضی‌شده و هر وضعیت دیگر یا بدنه‌ای که نتواند بخواند به‌عنوان خطا به حساب می‌آید و در هر دو حالت به عددهای ذخیره‌شده برمی‌گردد.
6. پاسخ درست همراه با زمان اندازه‌گیری در `<name>.json` نوشته می‌شود.

`fallback()` هر دو فایل `<name>.json` و `<name>.statusline.json` را می‌خواند و جدیدتر را نگه می‌دارد. پیش از نشان دادن عددهای ذخیره‌شده، زمان بازنشانی هر پنجره را بررسی می‌کند: پنجره‌ای که پس از ذخیره عددها بازنشانی شده باشد ۰٪ نشان می‌دهد، چون درصد قدیمی دیگر معتبر نیست. به همین دلیل `personal` در بالا `0%` را بدون زمان بازنشانی نشان می‌دهد.

نقطه پایانی دو قالب پاسخ دارد. قالب جدیدتر یک آرایه `limits` با ورودی‌های `session` (۵ ساعته)، `weekly_all` و `weekly_scoped` (ویژه هر مدل) دارد. قالب قدیمی‌تر شیءهای `five_hour`، `seven_day`، `seven_day_opus` و `seven_day_sonnet` را دارد. `ParseLive` هر دو را می‌خواند: آرایه `limits` اولویت دارد و شیءهای قدیمی آنچه را که آن پوشش نمی‌دهد کامل می‌کنند. بدنه‌ای که هیچ سقفی نداشته باشد به‌عنوان قالب تغییرکرده گزارش می‌شود و `ccam doctor` آن را به شما اطلاع می‌دهد.

### تمدید توکن‌ها

توکن‌های تمدید چرخشی‌اند: تمدید یکی از آن‌ها یک توکن تمدید جدید به شما می‌دهد و توکن قبلی را باطل می‌کند. اگر ccam ورود را در حالی تمدید کند که Claude Code با همان حساب در حال اجراست، آن نشست از حساب خارج می‌شود. بنابراین `ccam usage` توکن‌ها را می‌خواند و هرگز آن‌ها را نمی‌نویسد، مگر اینکه `--refresh` را بدهید. در آن صورت `Fetcher.refresh`:

1. حساب‌هایی را که با `ccam import` در همان محل ثبت شده‌اند رد می‌کند، چون `claude` معمولی ممکن است بدون اطلاع ccam از آن ورود استفاده کند؛
2. ورودهایی را که در Keychain سیستم macOS ذخیره شده‌اند رد می‌کند؛
3. یک فایل قفل، `$XDG_RUNTIME_DIR/ccam/profile-<name>.refresh.lock` (یا زیر `~/.local/state/ccam/locks/` وقتی آن متغیر تنظیم نشده باشد) می‌گیرد، تا دو فرایند ccam هرگز یک توکن را دو بار تمدید نکنند؛
4. زیر قفل، اگر نشستی از آن حساب در حال اجرا باشد رد می‌کند، و اگر فرایند دیگری توکن را از قبل تمدید کرده باشد از درخواست صرف‌نظر می‌کند؛
5. توکن تمدید را به نقطه پایانی توکن می‌فرستد و توکن‌های جدید را با `fsutil.AtomicWrite` در `.credentials.json` می‌نویسد و همه کلیدهای دیگر فایل را نگه می‌دارد.

### جمع‌آوری‌کننده خط وضعیت

Claude Code فرمان خط وضعیت را اجرا می‌کند و یک سند JSON را به ورودی آن می‌فرستد. ccam نام مدل و `rate_limits` را از آن می‌خواند:

1. `runStatusline` حساب را از `CCAM_PROFILE` پیدا می‌کند که ccam هنگام اجرای Claude Code تنظیم می‌کند، یا در غیر این صورت با مقایسه `CLAUDE_CONFIG_DIR` با پوشه‌های حساب‌ها.
2. `ParseStatusLine` مقدارهای `rate_limits.five_hour` و `rate_limits.seven_day` را می‌خواند. برای حساب‌های کلید API، یا پیش از نخستین پاسخ نشست، JSON هیچ سقف نرخی ندارد؛ در این حالت چیزی ذخیره نمی‌شود.
3. `SaveStatusLine` فایل `~/.local/state/ccam/usage/<name>.statusline.json` را می‌نویسد. `ccam usage` وقتی نقطه پایانی پاسخ ندهد از آن استفاده می‌کند.
4. ccam خط `[name] · model · 5h N% · 7d N%` را چاپ می‌کند. با `--wrap`، فرمان شما را با همان ورودی از طریق `sh -c` اجرا می‌کند و به‌جای آن `[name]` و پس از آن نخستین خط خروجی فرمان را چاپ می‌کند.

فرمان پیچیده‌شده ۲ ثانیه فرصت دارد. پس از آن متوقف می‌شود و خط فقط نام حساب را نشان می‌دهد، بنابراین یک فرمان کند نمی‌تواند خط وضعیت Claude Code را مسدود کند.

`ccam statusline install` مقدار `statusLine` را در `settings.json` هر حساب می‌نویسد. وقتی یک حساب از قبل فرمان خط وضعیت داشته باشد، ccam آن را به شکل `--wrap '<old command>'` نگه می‌دارد. `settings.json` که از طریق یک گروه به اشتراک گذاشته شده است یک بار و از طریق پیوند خود نوشته می‌شود، بنابراین همه حساب‌های گروه آن را دریافت می‌کنند. اجرای دوباره آن برای فایل‌هایی که از قبل از ccam استفاده می‌کنند `(already set)` را چاپ می‌کند.

## ایمنی و حالت‌های خاص

- `ccam usage` هرگز فایل توکن را تغییر نمی‌دهد، مگر اینکه `--refresh` را بدهید. وقتی یک ورود منقضی شده باشد، حساب را یک بار با `ccam <name>` اجرا کنید تا Claude Code آن را تمدید کند.
- `--refresh` هرگز به حساب‌های در حال اجرا، حساب‌های واردشده یا ورودهای Keychain دست نمی‌زند. تمدیدی که رد شود عددهای ذخیره‌شده و دلیل آن را نشان می‌دهد.
- نقطه پایانی مصرف به‌طور عمومی مستند نشده است و ممکن است تغییر کند. وقتی تغییر کند، همچنان عددهای ذخیره‌شده را می‌بینید و `ccam doctor` تغییر قالب را گزارش می‌دهد.
- وقتی نه عدد ذخیره‌شده‌ای باشد و نه پاسخی، ردیف `lookup failed:` و دلیل آن را نشان می‌دهد، برای مثال `no saved usage` با `--source cache`.
- فایل‌های حافظه نهان فقط درصدها و زمان‌های بازنشانی را نگه می‌دارند، هرگز توکن‌ها را.

## مرتبط

- [سقف مصرف و جابه‌جایی بین حساب‌ها](https://ccam.dev/fa/docs/usage-limits.md)
- [رفتن به حساب بعدی](https://ccam.dev/fa/features/next.md)
- [راهنمای کار با سقف مصرف](https://ccam.dev/fa/guides/usage-limit-workflow.md)
- [فرمان‌ها](https://ccam.dev/fa/docs/commands.md)