CLI Configuration

Currently in beta and not available for trial users. Paid users can request access via support@adsuploader.com.

The best way to get started with the CLI (command-line interface) is to understand how Ads Uploader works. The CLI follows the exact same structure as the web application. If you understand the web app and have uploaded ads through it, using the CLI will immediately make sense.

Any presets you build in the web interface are carried through to the CLI and accessible from it. Some users may find it easiest to set up their presets in the application and then switch to the CLI for day-to-day campaign work. Everything is still completely customizable from within the CLI.

Why use the CLI? It provides a different interface with an agentic focus for working through the same tried-and-tested Ads Uploader infrastructure. Loading up multiple batches is faster, and you can use AI to write ad copy and assemble ad builds. It is another way of using Ads Uploader.

Most users drive the CLI through an AI agent like Claude Code or Cursor. See Using with AI at the bottom of this page for how to hand the CLI to an agent once you're set up.

Install and Authenticate

Install the CLI globally with npm install -g @adsuploader/cli (requires Node.js 18+), then run ads login to authenticate through your browser. This uses your existing Ads Uploader account and Facebook connection.

Run the login command on the same device where you are already signed in to adsuploader.com, since the auth flow opens a browser window to verify your identity.

Setting Up Your Account

Once logged in, run ads accounts to see all ad accounts connected to your Meta account, then ads account act_123456789 to set your default. This is the same account selector you see in the web app.

Browsing Your Account

Before creating ads, you can browse your entire account structure from the CLI, just like you would click through campaigns, ad sets, and ads in the web app.

This is how you find the ad you want to copy settings from, or confirm which preset to use in your spec file.

Uploading Media

Upload images and videos to your ad account's media library with ads upload:

ads upload hero.jpg banner.mp4 promo.mp4
ads upload ./my-creatives/

This returns a batch ID that you will reference when creating ads. Run ads uploads to see your recent batches.

Variant grouping works automatically if you name files with ratio suffixes, just like it does in the web application. See Aspect Ratio Variations for how to name your files correctly.

Creating Ads

Ad creation has two steps: preview and create.

The Spec File

A JSON spec file tells the CLI what to build. The simplest spec references a saved preset and your upload batch:

{ "adPresetId": "your_preset_id", "uploadId": "batch_abc123" }

You can also copy settings from an existing ad instead of using a preset:

{ "copyFromAd": "120233848667930472", "uploadId": "batch_abc123" }

To find the right ad ID, browse your account with ads campaigns, ads campaign <id>, ads adset <id>, and ads ad <id>.

Preview First

Always preview before creating. Run ads create:preview spec.json to see exactly what would be created without touching Facebook. This catches configuration errors before anything goes live.

Create

When you are happy with the preview, run ads create spec.json. Ads go live by default, just like in the web app. To create them paused instead, add --status PAUSED or set "options": { "status": "PAUSED" } in the spec.

Full Reference

For the complete spec file format, all commands, flags, creative enhancements, carousel and flexible ad configuration, ad naming placeholders, and common patterns, see the CLI Full Reference.

Job Tracking

Ad creation runs in the background. The CLI streams progress automatically, but you can also check on a job later:

ads create and --follow watch for up to 30 minutes at a time. On very large batches the CLI may exit with a "Still running" message before the job finishes — that's not a failure. Resume with ads jobs JOB_ID --follow. The backend job keeps running regardless of whether you're watching. Exit code is 2 in that case (vs 0 success, 1 error).

Rate Limits

The CLI is rate-limited per user and per endpoint. Typical usage never hits the limits, but a runaway script will trigger a 429 Rate Limit Exceeded response with a Retry-After header. Don't wrap CLI commands in polling loops (watch, shell while loops); use ads jobs JOB_ID --follow for live progress instead.

Tips

• Always preview first. create:preview catches config errors before touching Facebook.
• Ads go live by default. Use --status PAUSED if you want to review them in Ads Manager first.
• Uploads are tied to an account. The batch ID only works with the account you uploaded to.
• Presets carry over from the web app. Build your presets in the web UI, then reference them by ID in the CLI.
• Run ads config to check your setup. Shows your current account, API URL, and credentials path.

Using with AI

The CLI is designed to be controlled by AI agents like Claude Code or Cursor. Once you've installed and authenticated, register the skill file so your agent understands every command and spec option on this page.

The skill file ships inside the npm package at node_modules/@adsuploader/cli/SKILL.md. In Claude Code, set it up as a custom slash command (e.g. /ads):

mkdir -p .claude/commands
cp node_modules/@adsuploader/cli/SKILL.md .claude/commands/ads.md

Then type /ads in Claude Code to load the skill before giving instructions. For other AI tools like Cursor, add SKILL.md as a rule or context file.

Security. The CLI authentication is tied to your IP address, and only one ad creation job can run at a time per account. The CLI is not intended to be plugged into other applications. It is an alternative interface for advanced media buyers.

Example prompt

Once set up, give your AI agent instructions like:

I have a bunch of new ad creatives in my downloads/ads folder. Upload them and create ads using the same settings as my Sales purchase campaign preset. Group them into ad sets of five named with today's date, with a $25 daily budget. Write unique copy for each image based on the image content. Pause at the ad set level and preview first.