{"_id":"x-ads-cli","_rev":"6-59053b56ba4e9adb48cc45a916baa5c5","name":"x-ads-cli","dist-tags":{"latest":"1.0.4"},"versions":{"0.1.0":{"name":"x-ads-cli","version":"0.1.0","keywords":["x-ads","ads","cli","ai-agent","api"],"author":{"name":"Benn Huang","email":"tohuangbin@gmail.com"},"license":"Apache-2.0","_id":"x-ads-cli@0.1.0","maintainers":[{"name":"bennhuang","email":"tohuangbin@gmail.com"}],"homepage":"https://github.com/Bin-Huang/x-ads-cli#readme","bugs":{"url":"https://github.com/Bin-Huang/x-ads-cli/issues"},"bin":{"x-ads-cli":"dist/index.js"},"dist":{"shasum":"b2edc98907cc041108c46e859cf860f689da4e6b","tarball":"https://registry.npmjs.org/x-ads-cli/-/x-ads-cli-0.1.0.tgz","fileCount":12,"integrity":"sha512-6I7w/AlmV0zmdW6wF+zudkadEkMzTpF3/Averztk9U3nxeWKMvRVyaMfbFCiin/+MMa7pd5ro5oVOE1K2PFuzw==","signatures":[{"sig":"MEQCIGZyFmq99MrKLCauT9Wo8vLA91shcR0J6QEl9bxPLDnyAiB+vqeAOkHyOFRXNy9rHcPp4IkZi+UEFGVT8/Js9Uqm0w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30099},"type":"module","engines":{"node":">=18"},"gitHead":"6314b72476d331984ec88b88587102339f462da8","scripts":{"build":"tsc","prepack":"pnpm build"},"_npmUser":{"name":"bennhuang","email":"tohuangbin@gmail.com"},"repository":{"url":"git+https://github.com/Bin-Huang/x-ads-cli.git","type":"git"},"_npmVersion":"10.8.2","description":"X Ads CLI for AI agents","directories":{},"_nodeVersion":"20.19.0","dependencies":{"commander":"^14.0.3"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be","devDependencies":{"typescript":"^5.9.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/x-ads-cli_0.1.0_1773660652489_0.5924478836670126","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"x-ads-cli","version":"1.0.0","keywords":["x-ads","ads","cli","ai-agent","api"],"author":{"name":"Benn Huang","email":"tohuangbin@gmail.com"},"license":"Apache-2.0","_id":"x-ads-cli@1.0.0","maintainers":[{"name":"bennhuang","email":"tohuangbin@gmail.com"}],"homepage":"https://github.com/Bin-Huang/x-ads-cli#readme","bugs":{"url":"https://github.com/Bin-Huang/x-ads-cli/issues"},"bin":{"x-ads-cli":"dist/index.js"},"dist":{"shasum":"f15680230a3059879cb82284a83a2f169f80bfd3","tarball":"https://registry.npmjs.org/x-ads-cli/-/x-ads-cli-1.0.0.tgz","fileCount":14,"integrity":"sha512-eQ0js4Gpj3pLVnlbgeKV4GJG5ieDWItXZPoFJ/ogt0etlBt7eBthZehoINL6OTzq9g/B9+RNti8l9hOPtpx4OA==","signatures":[{"sig":"MEYCIQC8hsDeA913ZuhXeop47OavqJNn1IcrLnXL5jn6cBoW8QIhAKFbZFH3f8939e2iC/UA/AcMj+AwcmIi8KvUnPQeqFK1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37397},"type":"module","engines":{"node":">=18"},"gitHead":"acaa209bee52c86fa0c3539bf5ae0ad1caf5ede7","scripts":{"build":"tsc","prepack":"pnpm build"},"_npmUser":{"name":"bennhuang","email":"tohuangbin@gmail.com"},"repository":{"url":"git+https://github.com/Bin-Huang/x-ads-cli.git","type":"git"},"_npmVersion":"10.8.2","description":"X Ads CLI for AI agents","directories":{},"_nodeVersion":"20.19.0","dependencies":{"commander":"^14.0.3"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be","devDependencies":{"typescript":"^5.9.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/x-ads-cli_1.0.0_1773728688563_0.08360532316691605","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"x-ads-cli","version":"1.0.1","keywords":["x-ads","ads","cli","ai-agent","api"],"author":{"name":"Benn Huang","email":"tohuangbin@gmail.com"},"license":"Apache-2.0","_id":"x-ads-cli@1.0.1","maintainers":[{"name":"bennhuang","email":"tohuangbin@gmail.com"}],"homepage":"https://github.com/Bin-Huang/x-ads-cli#readme","bugs":{"url":"https://github.com/Bin-Huang/x-ads-cli/issues"},"bin":{"x-ads-cli":"dist/index.js"},"dist":{"shasum":"5811c0d3dff1929378f02d607f1f7a96e53c7014","tarball":"https://registry.npmjs.org/x-ads-cli/-/x-ads-cli-1.0.1.tgz","fileCount":14,"integrity":"sha512-a37zUHonV0ctZfhvj+9zTp30G1Oe4ABnpVlbGRS1JXT7V9IZZZimG9tyip8/Dy0wvj5uXref07ShB4ofV1LiMA==","signatures":[{"sig":"MEUCIHP+Dq3BVTb3dthesBpbYa0RGhpLPtIddZfbXnQtQQjXAiEAsS6jxsyY2HRSPjr6uht9KOV03kDkBRarC6yi8OJoBKk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37377},"type":"module","engines":{"node":">=18"},"gitHead":"721b74df59020737b6281670d1ee8727d02421c7","scripts":{"build":"tsc","prepack":"pnpm build"},"_npmUser":{"name":"bennhuang","email":"tohuangbin@gmail.com"},"repository":{"url":"git+https://github.com/Bin-Huang/x-ads-cli.git","type":"git"},"_npmVersion":"10.8.2","description":"X Ads CLI for AI agents","directories":{},"_nodeVersion":"20.19.0","dependencies":{"commander":"^14.0.3"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be","devDependencies":{"typescript":"^5.9.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/x-ads-cli_1.0.1_1773739030497_0.8749401516891342","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"x-ads-cli","version":"1.0.2","keywords":["x-ads","ads","cli","ai-agent","api"],"author":{"name":"Benn Huang","email":"tohuangbin@gmail.com"},"license":"Apache-2.0","_id":"x-ads-cli@1.0.2","maintainers":[{"name":"bennhuang","email":"tohuangbin@gmail.com"}],"homepage":"https://github.com/Bin-Huang/x-ads-cli#readme","bugs":{"url":"https://github.com/Bin-Huang/x-ads-cli/issues"},"bin":{"x-ads-cli":"dist/index.js"},"dist":{"shasum":"5ff494f07da5306d5684870b9124667d407dac7e","tarball":"https://registry.npmjs.org/x-ads-cli/-/x-ads-cli-1.0.2.tgz","fileCount":14,"integrity":"sha512-Sdj9z+DCHP7pHlAm3unH8lN8eLj0i0N2SJoTL4gw5aQchG/lwBxYpeB3wxAqvvbZ+PEjwhO9P9qVekI4UKUQeQ==","signatures":[{"sig":"MEQCIGS4y5OEGq/mGuedQ15U1R1Mt270priSmWR8/b4XuCYhAiBxyxyJXSOUPYS34DEqKK3Cf7IzsyTLMYFqernqTdYcBw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37455},"type":"module","_from":"file:x-ads-cli-1.0.2.tgz","engines":{"node":">=18"},"scripts":{"build":"tsc"},"_npmUser":{"name":"bennhuang","email":"tohuangbin@gmail.com"},"_resolved":"/private/var/folders/rv/s95dj9fx5r96n8nt3c4j4r040000gn/T/a9009984d281eae1238e78b9d06ea15e/x-ads-cli-1.0.2.tgz","_integrity":"sha512-Sdj9z+DCHP7pHlAm3unH8lN8eLj0i0N2SJoTL4gw5aQchG/lwBxYpeB3wxAqvvbZ+PEjwhO9P9qVekI4UKUQeQ==","repository":{"url":"git+https://github.com/Bin-Huang/x-ads-cli.git","type":"git"},"_npmVersion":"10.8.2","description":"X Ads CLI for AI agents","directories":{},"_nodeVersion":"20.19.0","dependencies":{"commander":"^14.0.3"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/x-ads-cli_1.0.2_1773744591241_0.5378042876161664","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"x-ads-cli","version":"1.0.3","keywords":["x-ads","ads","cli","ai-agent","api"],"author":{"name":"Benn Huang","email":"tohuangbin@gmail.com"},"license":"Apache-2.0","_id":"x-ads-cli@1.0.3","maintainers":[{"name":"bennhuang","email":"tohuangbin@gmail.com"}],"homepage":"https://github.com/Bin-Huang/x-ads-cli#readme","bugs":{"url":"https://github.com/Bin-Huang/x-ads-cli/issues"},"bin":{"x-ads-cli":"dist/index.js"},"dist":{"shasum":"365604ecaef1a4d97796a86a877817b0ce9e8183","tarball":"https://registry.npmjs.org/x-ads-cli/-/x-ads-cli-1.0.3.tgz","fileCount":14,"integrity":"sha512-I3ehkbtGRIdheHfX02FVaxvVCl4Ig7ndjRYJQUb5DJd+SVTZUZeHEX44pLO41Di4IW2+tOiu9SXxWUGS130VvA==","signatures":[{"sig":"MEUCIC8s3Q3XQPCuyvhtuYm+G3W3E6+hIAARscKnYle6KGS8AiEAu4RaDAjb0c8iVl5LzPZpvJxnSvV/5ZghvELNpRcVEQ0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39809},"type":"module","engines":{"node":">=18"},"gitHead":"7360fd35ac3f73bcd2c50d4278628729805def58","scripts":{"build":"tsc","prepack":"pnpm build"},"_npmUser":{"name":"bennhuang","email":"tohuangbin@gmail.com"},"repository":{"url":"git+https://github.com/Bin-Huang/x-ads-cli.git","type":"git"},"_npmVersion":"10.8.2","description":"X Ads CLI for AI agents","directories":{},"_nodeVersion":"20.19.0","dependencies":{"commander":"^14.0.3"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be","devDependencies":{"typescript":"^5.9.3","@types/node":"^25.5.0"},"_npmOperationalInternal":{"tmp":"tmp/x-ads-cli_1.0.3_1773755198604_0.7965214346758245","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"x-ads-cli","version":"1.0.4","description":"X Ads CLI for AI agents","type":"module","bin":{"x-ads-cli":"dist/index.js"},"scripts":{"build":"tsc","prepack":"pnpm build"},"author":{"name":"Benn Huang","email":"tohuangbin@gmail.com"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/Bin-Huang/x-ads-cli.git"},"engines":{"node":">=18"},"keywords":["x-ads","ads","cli","ai-agent","api"],"packageManager":"pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be","devDependencies":{"@types/node":"^25.5.0","typescript":"^5.9.3"},"dependencies":{"commander":"^14.0.3"},"bugs":{"url":"https://github.com/Bin-Huang/x-ads-cli/issues"},"homepage":"https://github.com/Bin-Huang/x-ads-cli#readme","_id":"x-ads-cli@1.0.4","gitHead":"229a72eab10af488e194a3fbc51af93af52dbe7a","_nodeVersion":"20.19.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-oaV8b2gnZv4EaOQM4av4y9A3+QaUyfnKqyUMA6DuoziPS519Z37iZ4eOeQRYIaKUbJGH9FUXHXkFq6uCBCx7OQ==","shasum":"33471d6fe5dec3746718fa89d74e4be6bdee4014","tarball":"https://registry.npmjs.org/x-ads-cli/-/x-ads-cli-1.0.4.tgz","fileCount":14,"unpackedSize":39856,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDE4UfKDoHrUiJR5fMmsR2Ac2q//z5ASv8zf8INahHc8AIhAOEZLtryAJ57nZLWWpy9eVUn0HMHHJlErj73Zjj3oSgY"}]},"_npmUser":{"name":"bennhuang","email":"tohuangbin@gmail.com"},"directories":{},"maintainers":[{"name":"bennhuang","email":"tohuangbin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x-ads-cli_1.0.4_1773925349098_0.850176023826821"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T11:30:52.488Z","modified":"2026-03-19T13:02:29.363Z","0.1.0":"2026-03-16T11:30:52.626Z","1.0.0":"2026-03-17T06:24:48.762Z","1.0.1":"2026-03-17T09:17:10.633Z","1.0.2":"2026-03-17T10:49:51.380Z","1.0.3":"2026-03-17T13:46:38.731Z","1.0.4":"2026-03-19T13:02:29.234Z"},"bugs":{"url":"https://github.com/Bin-Huang/x-ads-cli/issues"},"author":{"name":"Benn Huang","email":"tohuangbin@gmail.com"},"license":"Apache-2.0","homepage":"https://github.com/Bin-Huang/x-ads-cli#readme","keywords":["x-ads","ads","cli","ai-agent","api"],"repository":{"type":"git","url":"git+https://github.com/Bin-Huang/x-ads-cli.git"},"description":"X Ads CLI for AI agents","maintainers":[{"name":"bennhuang","email":"tohuangbin@gmail.com"}],"readme":"# x-ads-cli\n\nX Ads CLI for AI agents (and humans). Pull engagement, billing, and conversion analytics for campaigns and promoted tweets, estimate reach, track media creatives, and more.\n\n**Works with:** OpenClaw, Claude Code, Cursor, Codex, and any agent that can run shell commands.\n\n## Installation\n\n```bash\nnpm install -g x-ads-cli\n```\n\nOr run directly: `npx x-ads-cli --help`\n\n## How it works\n\nBuilt on the official [X Ads API](https://docs.x.com/x-ads-api/introduction) (v12). Handles OAuth 1.0a signing natively with Node.js `crypto` (no external dependencies). Every command outputs structured JSON to stdout, ready for agents to parse without extra processing.\n\nCore endpoints covered:\n\n- **[Accounts](https://docs.x.com/x-ads-api/campaign-management#accounts)** -- list and inspect ad accounts\n- **[Campaigns](https://docs.x.com/x-ads-api/campaign-management#campaigns)** -- list campaigns under an account\n- **[Line Items](https://docs.x.com/x-ads-api/campaign-management#line-items)** -- list line items (ad groups) under an account\n- **[Analytics](https://docs.x.com/x-ads-api/analytics)** -- synchronous performance metrics\n\n## Setup\n\n### Step 1: Get X Ads API access\n\n1. Go to the [X Developer Portal](https://developer.x.com/) and sign in.\n2. Create a project and app if you don't have one.\n3. Apply for Ads API access -- your app must be approved for the Ads API tier (separate from the standard X API).\n\nAds API access requires approval. See [Getting Started](https://docs.x.com/x-ads-api/getting-started) for details.\n\n### Step 2: Get your API credentials\n\nIn the Developer Portal, under your app's \"Keys and Tokens\" page, obtain:\n\n- **API Key** (also called Consumer Key)\n- **API Secret** (also called Consumer Secret)\n- **Access Token**\n- **Access Token Secret**\n\nThe Access Token must belong to a user who has access to at least one X Ads account.\n\n### Step 3: Place the credentials file\n\nChoose one of these options:\n\n```bash\n# Option A: Default path (recommended)\nmkdir -p ~/.config/x-ads-cli\ncat > ~/.config/x-ads-cli/credentials.json << EOF\n{\n \"api_key\": \"YOUR_API_KEY\",\n \"api_secret\": \"YOUR_API_SECRET\",\n \"access_token\": \"YOUR_ACCESS_TOKEN\",\n \"access_token_secret\": \"YOUR_ACCESS_TOKEN_SECRET\"\n}\nEOF\n\n# Option B: Environment variables\nexport X_ADS_API_KEY=your_api_key\nexport X_ADS_API_SECRET=your_api_secret\nexport X_ADS_ACCESS_TOKEN=your_access_token\nexport X_ADS_ACCESS_TOKEN_SECRET=your_access_token_secret\n\n# Option C: Pass per command\nx-ads-cli --credentials /path/to/credentials.json accounts\n```\n\nCredentials are resolved in this order:\n1. `--credentials ` flag\n2. `X_ADS_API_KEY`, `X_ADS_API_SECRET`, `X_ADS_ACCESS_TOKEN`, `X_ADS_ACCESS_TOKEN_SECRET` env vars\n3. `~/.config/x-ads-cli/credentials.json` (auto-detected)\n\n### Step 4: Find your Ad Account ID\n\n```bash\nx-ads-cli accounts\n```\n\nThis returns all ad accounts accessible by the authenticated user. Use the account ID from the response in subsequent commands.\n\n## Usage\n\nAll commands output pretty-printed JSON by default. Use `--format compact` for compact single-line JSON.\n\n### accounts\n\nList all ad accounts accessible by the authenticated user.\n\n```bash\nx-ads-cli accounts\nx-ads-cli accounts --with-deleted\n```\n\n### account\n\nGet details of a specific ad account.\n\n```bash\nx-ads-cli account abc1x2\n```\n\n### campaigns\n\nList campaigns for an ad account.\n\n```bash\nx-ads-cli campaigns abc1x2\nx-ads-cli campaigns abc1x2 --campaign-ids id1,id2\nx-ads-cli campaigns abc1x2 --with-deleted --count 500\n```\n\nOptions:\n- `--campaign-ids ` -- filter by campaign IDs (comma-separated)\n- `--with-deleted` -- include deleted campaigns\n- `--count ` -- results per page (default 200, max 1000)\n- `--cursor ` -- pagination cursor from previous response\n\n### line-items\n\nList line items (ad groups) for an ad account. In the X Ads hierarchy, line items sit under campaigns and contain targeting, budget, and bid settings.\n\n```bash\nx-ads-cli line-items abc1x2\nx-ads-cli line-items abc1x2 --campaign-ids campaign_id_1\nx-ads-cli line-items abc1x2 --line-item-ids li1,li2\n```\n\nOptions:\n- `--campaign-ids ` -- filter by campaign IDs (comma-separated)\n- `--line-item-ids ` -- filter by line item IDs (comma-separated)\n- `--with-deleted` -- include deleted line items\n- `--count ` -- results per page (default 200, max 1000)\n- `--cursor ` -- pagination cursor\n\n### stats\n\nGet synchronous analytics for an ad account. Supports up to 7 days of data per request.\n\n```bash\n# Campaign-level daily metrics\nx-ads-cli stats abc1x2 \\\n --entity CAMPAIGN \\\n --entity-ids campaign_id_1,campaign_id_2 \\\n --start-time 2026-03-01T00:00:00Z \\\n --end-time 2026-03-07T00:00:00Z \\\n --granularity DAY \\\n --metric-groups ENGAGEMENT,BILLING\n\n# Line item hourly metrics\nx-ads-cli stats abc1x2 \\\n --entity LINE_ITEM \\\n --entity-ids line_item_id_1 \\\n --start-time 2026-03-15T00:00:00Z \\\n --end-time 2026-03-16T00:00:00Z \\\n --granularity HOUR \\\n --metric-groups ENGAGEMENT,BILLING,VIDEO\n```\n\nOptions:\n- `--entity ` -- entity type: `CAMPAIGN`, `LINE_ITEM`, `PROMOTED_TWEET`, `MEDIA_CREATIVE`, `FUNDING_INSTRUMENT`, `ORGANIC_TWEET` (required)\n- `--entity-ids ` -- entity IDs, comma-separated (required)\n- `--start-time