{"_id":"@ai-cost-guard/cli","name":"@ai-cost-guard/cli","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@ai-cost-guard/cli","version":"1.0.2","description":"Monitor every LLM API call and never get surprised by your AI bill again. Real-time cost tracking for OpenAI, Anthropic, Gemini across 50+ models with analytics, budget alerts, and optimization tips.","bin":{"ai-cost":"dist/index.js","ai-cost-cli":"dist/index.js"},"main":"dist/index.js","scripts":{"build":"tsc","dev":"ts-node src/index.ts","start":"node dist/index.js","prepublishOnly":"npm run build"},"keywords":["ai","llm","cost","cli","terminal","openai","gpt","gpt-4","chatgpt","anthropic","claude","gemini","monitor","monitoring","optimization","api-cost","token-tracking","budget","analytics","devtools","developer-tools","ai-ops"],"author":{"name":"aicostguard"},"license":"MIT","homepage":"https://aicostguard.com","repository":{"type":"git","url":"git+https://github.com/aicostguard/cli.git"},"bugs":{"url":"https://github.com/aicostguard/cli/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"chalk":"^4.1.2","cli-table3":"^0.6.5","commander":"^12.1.0","inquirer":"^8.2.6","ora":"^5.4.1","posthog-node":"^5.28.0"},"devDependencies":{"@types/inquirer":"^8.2.10","@types/node":"^22.0.0","typescript":"^5.7.0"},"_id":"@ai-cost-guard/cli@1.0.2","gitHead":"5ae774def75839dcd8c802e85107bf6ab5c563f3","types":"./dist/index.d.ts","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-yrOSVjISyJN+iEQ5xv9gicYfgfG8YVlVqeca9zdiKPlOqDN9/YLLzmKZCmbcJrKqf6I73NBme2zD+06bVi10tA==","shasum":"61f47b539e571807fa83d6e52de7374cd3ea0f1a","tarball":"https://registry.npmjs.org/@ai-cost-guard/cli/-/cli-1.0.2.tgz","fileCount":50,"unpackedSize":137122,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDkzJYF1+WiTmeEG3VLcybTiwci97WCU/absiHWKVwUnwIgFXVWevf/frjhOT+mQN4Ms+smuTiMmmaYK0PeyuwobOs="}]},"_npmUser":{"name":"aicostguard","email":"km003355@gmail.com"},"directories":{},"maintainers":[{"name":"aicostguard","email":"km003355@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cli_1.0.2_1773055035272_0.23992084572272665"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-09T11:17:15.208Z","1.0.2":"2026-03-09T11:17:15.412Z","modified":"2026-03-09T11:17:15.620Z"},"maintainers":[{"name":"aicostguard","email":"km003355@gmail.com"}],"description":"Monitor every LLM API call and never get surprised by your AI bill again. Real-time cost tracking for OpenAI, Anthropic, Gemini across 50+ models with analytics, budget alerts, and optimization tips.","homepage":"https://aicostguard.com","keywords":["ai","llm","cost","cli","terminal","openai","gpt","gpt-4","chatgpt","anthropic","claude","gemini","monitor","monitoring","optimization","api-cost","token-tracking","budget","analytics","devtools","developer-tools","ai-ops"],"repository":{"type":"git","url":"git+https://github.com/aicostguard/cli.git"},"author":{"name":"aicostguard"},"bugs":{"url":"https://github.com/aicostguard/cli/issues"},"license":"MIT","readme":"# ai-cost-cli\n\n> **AI Cost Guard CLI** -- See exactly how much money you are spending on AI (OpenAI, Anthropic, Gemini) right inside your terminal.\n\nThink of it like a **bank statement for your AI API bills** -- live, colorful, and completely free.\n\n[![npm version](https://img.shields.io/npm/v/ai-cost-cli.svg)](https://www.npmjs.com/package/@ai-cost-guard/cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js >= 16](https://img.shields.io/badge/node-%3E%3D16-brightgreen)](https://nodejs.org)\n\n---\n\n## What Does This Do?\n\nEvery time your app calls the OpenAI, Anthropic, or Google AI APIs, it costs you money (charged per \"token\").\n\nThis CLI connects to your **AI Cost Guard account** and shows you:\n\n- Total AI **spending** for the last 7, 30, or 90 days\n- **Which model costs the most** (GPT-4o vs Claude vs Gemini)\n- **Smart suggestions** to switch to a cheaper model and save 40-80%\n- **Live pricing** for 50+ AI models\n\n---\n\n## Getting Started -- Full Step-by-Step Guide\n\nFollow these 5 steps in order. Do not skip Step 2 -- you cannot use the CLI without an account and a project.\n\n---\n\n### Step 1 -- Install the CLI\n\nOpen your terminal and run:\n\n```bash\nnpm install -g @ai-cost-guard/cli\n```\n\nYou will now have two command aliases (both do the same thing):\n\n```bash\nai-cost-cli --help   # full command\nai-cost --help       # shorthand\n```\n\n---\n\n### Step 2 -- Create a Free Account\n\nYou need an account before you can do anything else.\n\n#### Option A -- Sign up from your terminal (fastest)\n\n```bash\nai-cost-cli signup\n```\n\nThe CLI will ask for:\n- Your name\n- Your email address\n- A password (minimum 8 characters)\n\nYour account is created instantly.\n\n#### Option B -- Sign up on the website\n\n1. Go to **https://aicostguard.com**\n2. Click the **\"Get Started\"** button (top-right of the homepage)\n3. Fill in your name, email address, and password\n4. Click **\"Sign Up\"**\n\nYou will land on your dashboard automatically.\n\n---\n\n### Step 3 -- Create a Project and Get Your API Key\n\nA **project** is how AI Cost Guard organises your AI costs.\nThink of it like a folder -- one project per app you build.\n\nYou must create at least one project before you can get an API key.\n\n#### Option A -- Create a project from your terminal (fastest)\n\n```bash\nai-cost-cli projects create\n```\n\nThe CLI will ask for:\n- **Project name** (e.g. `My Chatbot App`)\n- **Description** (optional, e.g. `Tracks GPT-4o costs for my support bot`)\n\nYour project is created instantly and its API key is saved automatically -- no copy-paste needed.\nYou can run `ai-cost-cli analyze` right away.\n\n#### Option B -- Create a project on the website:\n\n```\n1.  Log in at  https://aicostguard.com\n2.  You are now on the Dashboard\n3.  Click \"Projects\" in the left sidebar\n4.  Click the \"New Project\" button (top right of the page)\n5.  Fill in:\n      - Project Name   e.g.  My Chatbot App\n      - Description    e.g.  Tracks GPT-4o costs for my support bot\n6.  Click \"Create Project\"\n7.  Your new project card appears on the page\n8.  On that project card, click the \"API Keys\" button\n9.  You will see a default API key -- it looks like:  acg_live_abc123def456...\n10. Click \"Copy\" to copy it to your clipboard\n```\n\n> Tip: You can also click \"Generate New Key\" on that screen if you want a fresh key.\n\n#### Or let the CLI fetch your key automatically (after logging in):\n\n```bash\nai-cost-cli login\n```\n\nAfter login the CLI will:\n1. Show you a numbered list of all your projects\n2. Ask you to pick one\n3. Automatically save that project's API key -- no copy-paste needed\n\n---\n\n### Step 4 -- Connect the CLI to Your Project\n\n#### Option A -- Log in and pick a project (recommended for most people)\n\n```bash\nai-cost-cli login\n```\n\nThe CLI logs you in, lists your projects, and saves the key automatically.\n\n#### Option B -- Connect directly with your API key\n\n```bash\nai-cost-cli connect --key acg_live_xxxxxxxxxxxx\n```\n\nReplace `acg_live_xxxxxxxxxxxx` with the key you copied in Step 3.\n\n#### Verify you are connected:\n\n```bash\nai-cost-cli status\n```\n\nYou should see your project name, email, and a masked API key.\n\n---\n\n### Step 5 -- See Your AI Costs\n\n```bash\nai-cost-cli analyze\n```\n\nThis prints a full cost breakdown right in your terminal.\n\n```bash\nai-cost-cli analyze --days 7    # last 7 days\nai-cost-cli analyze --days 90   # last 3 months\n```\n\n---\n\n## All Commands at a Glance\n\n| Command | What it does |\n|---------|-------------|\n| `ai-cost-cli signup` | Create a FREE account -- **start here if you are new** |\n| `ai-cost-cli login` | Log in and connect to a project automatically |\n| `ai-cost-cli projects create` | Create a new project and get an API key |\n| `ai-cost-cli projects list` | List all your projects and switch active project |\n| `ai-cost-cli connect --key YOUR_KEY` | Connect using an API key directly |\n| `ai-cost-cli status` | Check whether you are connected |\n| `ai-cost-cli analyze` | Full AI cost report (last 30 days) |\n| `ai-cost-cli analyze --days 7` | Report for last 7 days |\n| `ai-cost-cli analyze --days 90` | Report for last 90 days |\n| `ai-cost-cli optimize` | Get tips to cut your AI bill |\n| `ai-cost-cli models` | Browse all AI models and their live pricing |\n\n---\n\n## How to Find Your API Key (Step by Step)\n\nIf you already have an account and just need your API key:\n\n```\n1.  Open    https://aicostguard.com\n2.  Click \"Log In\" -- enter your email and password\n3.  You are now on the Dashboard\n4.  Click \"Projects\" in the left sidebar\n5.  Find your project card\n6.  Click the \"API Keys\" button on that card\n7.  Copy the key that starts with  acg_live_\n8.  In your terminal run:\n\n      ai-cost-cli connect --key acg_live_YOUR_KEY_HERE\n```\n\n---\n\n## Command Reference\n\n### `signup` -- Create a New Account\n\n```bash\nai-cost-cli signup\n```\n\nPrompts for your name, email, and password. Creates your account and logs you in immediately.\n**This is the very first command you should run if you are new.**\n\n---\n\n### `login` -- Log In and Select a Project\n\n```bash\nai-cost-cli login\nai-cost-cli login --email you@example.com\n```\n\n| Option | Description |\n|--------|-------------|\n| `-e, --email <email>` | Pre-fill your email so you skip that prompt |\n\nWhat happens after you log in:\n- You are authenticated\n- The CLI fetches all your projects from the server\n- You pick one from a numbered list\n- That project's API key is saved automatically to your computer\n\n---\n\n### `connect` -- Connect With an API Key\n\n```bash\nai-cost-cli connect --key acg_live_xxxxxxxxxxxx\n```\n\n| Option | Description |\n|--------|-------------|\n| `-k, --key <apiKey>` | Your project API key (starts with `acg_live_`) |\n\nUse this if you already have your API key and want to skip the login flow.\n\n---\n\n### `projects create` -- Create a New Project\n\n```bash\nai-cost-cli projects create\n```\n\nCreates a brand-new project and saves its API key to your computer automatically.\nYou must be logged in first (run `ai-cost-cli login` if you have not already).\n\nThe CLI will ask for:\n- **Project name** (2 to 100 characters, e.g. `My Chatbot App`)\n- **Description** (optional, e.g. `Tracks GPT-4o costs for my support bot`)\n\nAfter creation you will see:\n- Your new project name\n- A masked version of your API key\n- Confirmation that the key has been saved\n\nYou can then run `ai-cost-cli analyze` immediately -- no copy-paste needed.\n\n> **Tip:** When you sign up with `ai-cost-cli signup`, the CLI will automatically\n> offer to create your first project right away so you never have to leave your terminal.\n\n---\n\n### `projects list` -- List All Projects\n\n```bash\nai-cost-cli projects list\n```\n\nFetches all your projects from the server and displays them in a numbered table:\n\n```\n  #   Project Name        Project ID    API Key\n  1   My Chatbot App      a1b2c3d4      acg_live_****...abc\n  2   Analytics Bot       e5f6g7h8      acg_live_****...xyz\n```\n\nAfter the list is shown the CLI will ask you to **pick a number**.\nThe project you choose becomes the **active project** -- its API key is saved\nautomatically so all future `analyze` and `optimize` commands use it.\n\nUse this command any time you want to switch between projects.\n\n---\n\n### `status` -- Check Your Connection\n\n```bash\nai-cost-cli status\n```\n\nShows:\n- Whether you are connected (yes or no)\n- Your API key (masked for safety)\n- Project name\n- Your logged-in email\n- Which server you are connected to\n\n---\n\n### `analyze` -- See Your Cost Report\n\n```bash\nai-cost-cli analyze\nai-cost-cli analyze --days 7\nai-cost-cli analyze --days 90 --model gpt-4o\nai-cost-cli analyze --provider anthropic\n```\n\n| Option | Description |\n|--------|-------------|\n| `-d, --days <n>` | How many days back to look (default: 30) |\n| `-m, --model <model>` | Filter to one specific model |\n| `-p, --provider <provider>` | Filter by provider: `openai`, `anthropic`, or `google` |\n\nThe report shows:\n- Total money spent\n- Total tokens used (input and output separately)\n- Cost broken down by each model\n- Day-by-day cost chart\n- Response time statistics\n\n---\n\n### `optimize` -- Get Cost-Cutting Tips\n\n```bash\nai-cost-cli optimize\nai-cost-cli optimize --days 7\n```\n\n| Option | Description |\n|--------|-------------|\n| `-d, --days <n>` | Days of usage to analyse (default: 30) |\n\nLooks at which models you are using and finds cheaper alternatives that do the same job.\nYou can often save **40-80%** just by switching models.\n\n---\n\n### `models` -- Browse All AI Pricing\n\n```bash\nai-cost-cli models\nai-cost-cli models --provider openai\nai-cost-cli models --provider anthropic\n```\n\n| Option | Description |\n|--------|-------------|\n| `-p, --provider <provider>` | Filter by provider name (case-insensitive) |\n\nShows a colour-coded table: input price per 1M tokens, output price per 1M tokens, and a cost tier label (budget / standard / premium).\n\n---\n\n## Where Is My Login Saved?\n\nEverything is stored only on your own computer (never uploaded anywhere) at:\n\n```\n~/.ai-costguard/config.json\n```\n\nTo log out and erase all saved data:\n\n```bash\nrm ~/.ai-costguard/config.json\n```\n\n---\n\n## Supported AI Providers\n\n| Provider | Example Models |\n|----------|---------------|\n| **OpenAI** | gpt-4o, gpt-4o-mini, gpt-4-turbo, o1, o3-mini |\n| **Anthropic** | claude-3-5-sonnet, claude-3-5-haiku, claude-3-opus |\n| **Google** | gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash |\n| **Cohere** | command-r-plus, command-r |\n\nRun `ai-cost-cli models` for the full live list with current pricing.\n\n---\n\n## Requirements\n\n- **Node.js** version 16 or newer -- download at https://nodejs.org\n- A **free AI Cost Guard account** -- sign up at https://aicostguard.com/signup\n\n---\n\n## Troubleshooting\n\n**\"Connection refused\" or network error**\n- Check your internet connection\n- The CLI connects to https://api.aicostguard.com\n\n**\"Invalid credentials\" when logging in**\n- Double-check your email and password\n- Reset your password at: https://aicostguard.com/forgot-password\n\n**\"No projects found\" after login**\n- You need to create a project first -- you can do it right from your terminal:\n  ```bash\n  ai-cost-cli projects create\n  ```\n- Or go to https://aicostguard.com/dashboard/projects, click \"New Project\", fill in the name, then run `ai-cost-cli login` again\n\n**\"Invalid API key\"**\n- Make sure you copied the full key (it starts with `acg_live_`)\n- Run: `ai-cost-cli connect --key acg_live_YOUR_FULL_KEY_HERE`\n\n**Still stuck?**\n- Email: info@aicostguard.com\n- GitHub Issues: https://github.com/aicostguard/cli/issues\n\n---\n\n## Links\n\n| | |\n|--|--|\n| Website | https://aicostguard.com |\n| Sign Up Free | https://aicostguard.com/signup |\n| Dashboard | https://aicostguard.com/dashboard |\n| Projects | https://aicostguard.com/dashboard/projects |\n| Full Docs | https://aicostguard.com/docs |\n| npm | https://www.npmjs.com/package/@ai-cost-guard/cli |\n| Report a Bug | https://github.com/aicostguard/cli/issues |\n\n---\n\n## License\n\nMIT (c) AI Cost Guard -- https://aicostguard.com\n","readmeFilename":"README.md","_rev":"1-4d08102b2af0d8f467872fa61ecc09a3"}