CLI Configuration

Currently in beta and not available for trial users. Paid users can request access via [email protected].

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.

Using with AI

The CLI is designed to be controlled by AI agents like Claude Code or Cursor. It ships with a skill file (SKILL.md) that describes every command and spec option so the agent knows how to operate the CLI on your behalf.

The documentation below covers how to set up and use the CLI yourself, but most users will use an LLM to control it. To get started, paste a prompt like this into your AI tool:

Install the Ads Uploader CLI by running npm install -g @adsuploader/cli, then run ads login to authenticate. This will open a browser window. I am already logged into my Ads Uploader account in this browser.

You need to run this on the same device where you are already logged into your Ads Uploader account, since the authentication flow opens your browser to verify your identity.

Once authenticated, register the skill file so your AI agent understands the full CLI. The skill file is at node_modules/@adsuploader/cli/SKILL.md and describes every command and spec option. 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, you can 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.

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.

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:

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.