CLI Configuration

The Ads Uploader CLI (command-line interface) lets you upload media and create Meta ads from a terminal. CLI access is for paid plans and is not available during a trial.

The CLI follows the same structure as the web app. If you have uploaded ads through the web app, the CLI will make sense straight away: you pick a source ad or preset, add your media, preview, then create.

Presets you build in the web app show up in the CLI, and you can save new API presets from the CLI with ads presets:save. The CLI also uses the same saved build references as the web uploader and MCP, so you can carry on with an in-progress build without starting again.

Why use the CLI? It gives you the same Ads Uploader launch pipeline through an interface built for AI agents. Loading several batches is faster, and you can let an agent write ad copy and assemble builds for you. Choose the CLI when you want to run your whole operation through an agent. For small, targeted help inside a web-first workflow, see CLI or MCP? on the MCP page.

Most people drive the CLI through an AI agent such as Claude Code or Cursor. See Using with AI below.

Install and Sign In

The CLI needs Node.js 18 or later. Install it from npm:

npm install -g @adsuploader/cli

Then sign in:

ads login

ads login opens your browser so you can approve the sign-in with your Ads Uploader account. Run it on a computer where you can open a browser and sign in to adsuploader.com. The CLI then uses your existing Meta connection.

How long a login lasts. A login token lasts 30 days. After that, run ads login again. You can see and revoke your CLI sessions under Account > Profile in the CLI Sessions card.

Updating. The CLI tells you when a new version is out. Update with:

npm update -g @adsuploader/cli

Run ads --version to see which version you have.

Set Your Ad Account

Run ads accounts to list the ad accounts connected to your Meta account, then set a default:

ads account act_123456789

This is the same as the account selector in the web app. If you have just been given access to a new ad account in Meta, run ads accounts:refresh to fetch the list again straight away.

Browse Your Account

Before you create ads, you can click through your account from the terminal, just as you would in the web app:

This is how you find the ad to copy settings from, or the preset or build to use.

Upload Media

Upload images and videos to your ad account with ads upload:

ads upload hero.jpg banner.mp4 promo.mp4
ads upload ./my-creatives/
ads upload hero.jpg "https://cdn.example.com/banner.mp4"
ads upload "https://drive.google.com/file/d/.../view"
ads upload:drive "https://drive.google.com/drive/folders/..."

Each upload returns a batch ID. You use it when you create ads. Run ads uploads to see your recent batches.

ads upload spots HTTPS links by itself. You can mix local files and links in one command: local files go first, then Ads Uploader downloads each link on its server into the same batch. That way, ratio grouping and thumbnail matching still work across everything. Public Google Drive file links work like any other link. For a whole Drive folder, use ads upload:drive; the folder must be shared as Anyone with the link (Viewer).

Name your files with ratio suffixes and the CLI groups the versions for you, just like the web app. See Aspect Ratio Variations.

If some files fail (for example, because of a network drop), run ads upload --retry-failed to retry the failed files from your last failed batch. Add a batch ID to retry a specific batch.

Create Ads

Creating ads has two steps: preview and create.

The Spec File

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

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

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

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

To find the ad ID, browse with ads campaigns, ads campaign <id>, ads adset <id> and ads ad <id>. Ads built from an existing Page post cannot be used as templates, because they have no copyable creative settings.

You can also skip the spec file and launch a saved build with --build <buildId>.

Preview First

Always preview before you create. ads create:preview spec.json shows exactly what would be created, without creating anything in Meta. It catches setup mistakes before anything goes live.

Create

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

Duplicate Existing Ads by Post ID

The CLI can also run the Duplicator, which copies an existing ad into another campaign or ad set while keeping its post engagement:

ads duplicator:post-id --account act_123 --post 1234567890_9876543210 --campaign 120200000000000000 --new-adset "Winners {AdName}" --paused

Preview the source-to-destination mapping first by running the same arguments with ads duplicator:post-id:preview. See Post-ID Duplication Flags for every flag and the spec format.

Full Reference

For every command and flag, the full spec format, creative enhancements, carousel, flexible and Multi Media ads, naming placeholders and spec limits, see the CLI Full Reference.

Track Jobs

Ad creation runs in the background. The CLI streams progress while it runs, and you can check on a job later:

ads create and --follow watch a job for up to 30 minutes at a time. On very large batches the CLI may stop watching with a "Still running" message before the job ends. That is not a failure: the job keeps running on the server. Pick it up again with ads jobs JOB_ID --follow. In that case the exit code is 2 (0 means success and 1 means an error).

You can run one ad creation job at a time per user. If you start another while one is running, the CLI tells you to wait for it to finish or cancel it.

Rate Limits

The CLI is rate limited per user and per kind of request. Normal use never hits the limits, but a runaway script gets a 429 Rate Limit Exceeded response with a Retry-After header. Do not wrap CLI commands in polling loops (such as watch or shell while loops). Use ads jobs JOB_ID --follow for live progress instead.

Settings and Environment Variables

Run ads config to check your setup. It shows whether you are signed in, your email, your default ad account, the API URL and the config folder (~/.config/adsuploader/). Your login is saved in credentials.json in that folder, readable only by you. ads whoami shows your email, default account and API URL.

Tips

• Always preview first. create:preview catches setup mistakes before any Meta ads are created.
• Ads go live by default. Use --status PAUSED if you want to check them in Ads Manager first.
• Uploads belong to one ad account. A batch ID only works with the ad account you uploaded to.
• Presets carry over from the web app. Build presets in the web app, or save API presets with ads presets:save, then use them by ID in the CLI.

Using with AI

The CLI is built to be driven by AI agents such as Claude Code or Cursor. After you install and sign in, give your agent the skill file so it knows every command and spec option.

The skill file ships inside the npm package. For the global install above, it is at:

"$(npm root -g)/@adsuploader/cli/SKILL.md"

In Claude Code, install it as a skill named ads:

mkdir -p .claude/skills/ads
cp "$(npm root -g)/@adsuploader/cli/SKILL.md" .claude/skills/ads/SKILL.md

Claude Code then loads it when you ask for ad work, or you can type /ads. In other AI tools such as Cursor, add SKILL.md as a rule or context file.

The CLI is an interface for media buyers and their agents. It is not meant to be built into other applications.

Example Prompt

Once it is set up, give your agent instructions like:

I have new ad creatives in my downloads/ads folder. Upload them and create ads using the same settings as my Summer Sale purchase 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 what it shows. Pause at the ad set level and preview first.

API Access

The CLI and the MCP server both talk to the Ads Uploader v1 API. They use the token you get from ads login or from signing in to the MCP server. There are no standalone API keys today, so use the CLI or MCP when you want programmatic access to Ads Uploader.

Partnership Ads

The CLI can launch partnership ads in two ways:

• With your own media. Use a normal image, video, carousel, flexible, Multi Media or ratio-variant spec and add profile.partnership.enabled: true with your partner's IDs. You can set a different partner per ad or per ad set, or choose No Partner for some rows.
• From existing Instagram posts. Import an authorized Instagram post by URL, shortcode, media ID or ad code with mediaItems[].kind: "partnershipPost".

Every partner needs approved partnership advertising access, and approval is checked again at preview and at create. For the full spec shapes, scoping keys and limits, see Partnership ads with your own media and Instagram existing-post partnership spec in the CLI Full Reference.