Advertising CLI commands

Buyer: list the networks this project was invited into, and inspect one network's permitted inventory and slots.

ads networks list
ads networks show <seller-project-id>

screenrig ads networks list

Seller: inspect or create this project's own network and set its default rate.

ads network show
ads network create --name NAME
ads network rate --rate-mcr-per-15s MCR --expect-rev REVISION

screenrig ads network rate --rate-mcr-per-15s 1000 --expect-rev 3

--name is at most 120 characters. --rate-mcr-per-15s is a positive whole number of mcr per 15 seconds of completed playback, and --expect-rev is the network's revision from ads network show. A changed effective rate pauses affected campaigns until each buyer accepts a fresh quote.

Seller: opt an owned screen in or out of advertising and describe it to invited buyers.

ads inventory list
ads inventory update <screen-id> [--enabled | --disabled] [--site-name NAME]
    [--city CITY] [--region REGION] [--venue-type TYPE] [--audience-tags TOKENS]
    [--placement TEXT] [--public-description TEXT]
    [--rate-mcr-per-15s MCR | --clear-rate]
    [--impressions-per-hour N | --clear-impressions-per-hour] [--expect-rev REVISION]

screenrig ads inventory update scr_LOBBY --enabled --venue-type cafe

Omitted flags keep their current values. A new inventory row needs --enabled or --disabled. --impressions-per-hour records your estimate of the impressions the screen delivers in an hour: each completed play then counts that estimate times the seconds played over 3600 as estimated_impressions in ads reports spend, ads reports delivery and ads direct report.

update needs at least one flag. --audience-tags takes up to 20 comma-separated tags, each at most 32 letters, digits or underscores. --clear-rate returns the screen to the project's default rate and --clear-impressions-per-hour removes the estimate. --expect-rev replaces the stored row's revision as the precondition and is refused for a screen with no row yet.

Seller: define reusable ad slots. A slot changes nothing on the glass until its adslot page is placed in a playlist.

ads slots list
ads slots create --name NAME --accepted-media image,video
    [--max-image-duration-ms MS] [--max-video-duration-ms MS]
    [--rate-mcr-per-15s MCR | --clear-rate] [--enabled | --disabled] [--vast-tag-url URL]
ads slots update <slot-id> --expect-rev REVISION [--name NAME]
    [--accepted-media image,video] [--max-image-duration-ms MS] [--max-video-duration-ms MS]
    [--rate-mcr-per-15s MCR | --clear-rate] [--enabled | --disabled]
    [--vast-tag-url URL | --clear-vast-tag-url]

screenrig ads slots create --name "Lobby break" --accepted-media image,video
screenrig ads slots create --name "Lobby video" --accepted-media video --vast-tag-url https://ads.example.com/vast.xml
screenrig ads slots update ads_LOBBY --clear-vast-tag-url --expect-rev 2

A new slot is enabled unless --disabled is given. --accepted-media is image, video or both, comma-separated. Omitted duration limits are 30000 ms; an image limit is 5000 to 30000 ms and a video limit 5000 to 120000 ms. --rate-mcr-per-15s is a positive whole number that overrides the screen or project rate for this slot, and --clear-rate removes the override. update keeps every field you omit, and a changed effective rate pauses affected campaigns until each buyer accepts a fresh quote. --vast-tag-url is an HTTPS URL of at most 2048 characters.

--vast-tag-url sets the seller's own VAST 2-4 ad tag, tried when no invited campaign fills the slot on your own screens; the slot must accept video. The URL is HTTPS on port 443 or 8443 to a public host. The backend fetches it, follows up to five Wrappers, ingests the chosen progressive MP4 or WebM into the project's media, and fires Impression, creativeView and start on an accepted start, complete on an accepted completion, and Error on failure; there are no quartile trackers. The macros [CACHEBUSTING], [TIMESTAMP], [SCREENRIG_SCREEN_ID], [SCREENRIG_SLOT_ID] and [SCREENRIG_PAGE_ID] are expanded, and buyers never see the tag. On update, --vast-tag-url replaces the tag and --clear-vast-tag-url removes it; the two do not combine, and omitting both keeps the stored tag. ads slots list shows vast_tag_url to the owning seller. A slot that nothing can fill on a screen (no VAST tag and, on a screen opted in to advertising, no direct campaign that has not ended and no active, pending or paused invited campaign naming it) is left out of that screen's manifest, and screen show lists it in ad_quiet_slots, so the Player stops asking. A campaign, tag or opt-in that could fill it brings it back.

Use the shared invitations commands above:

screenrig invitations create --kind ad-buyer --email owner@bakery.example --screen-id scr_LOBBY --policy review_required
screenrig invitations list --kind ad-buyer
screenrig invitations revoke ID

An ad-buyer invitation goes by email, never by link, and needs at least one --screen-id or --slot-id (comma-separated). --policy is trusted (the default) or review_required.

The invited person accepts in the dashboard. A signed-in person selects their buying project and confirms with a fresh passkey proof. A person without a login creates one and an advertiser-only project during acceptance.

Seller: change or revoke an admitted buyer's review policy and inventory scope.

ads memberships list
ads memberships update <membership-id> --expect-rev REVISION
    [--policy trusted|review_required] [--screen-id IDS] [--slot-id IDS]
ads memberships revoke <membership-id>

screenrig ads memberships list

update keeps the stored policy and scope for omitted flags. trusted plays the buyer's creatives without review; review_required holds each creative version for your decision. --screen-id and --slot-id take comma-separated ids and replace the whole list, and an empty value allows none.

Revocation stops new ad plays and keeps financial history.

Buyer: bind ready owned media to an immutable creative with approved copy.

ads creatives list
ads creatives create --media-id ID --copy TEXT
ads creatives show <creative-id>

screenrig ads creatives create --media-id med_123 --copy "Fresh bread daily"

Binding a creative charges nothing and does not upload the media again. An approved creative never changes in place: edit the source media and bind a new creative. --copy is at most 500 characters. show lists each seller network's review of the creative (pending, approved, rejected or changes_requested) with the seller's reason.

Buyer: draft a campaign, price it, and activate it by accepting the quote.

ads campaigns list
ads campaigns show <campaign-id>
ads campaigns create <file>
ads campaigns update <campaign-id> <file> --expect-rev REVISION
ads campaigns preview <campaign-id> [--expect-rev REVISION]
ads campaigns activate <campaign-id> --quote-id ID --expect-rev REVISION
ads campaigns pause <campaign-id> --expect-rev REVISION
ads campaigns resume <campaign-id> --expect-rev REVISION
ads campaigns accept-rates <campaign-id> --quote-id ID --expect-rev REVISION

screenrig ads campaigns preview cmp_123

A draft reserves nothing. preview returns a time-limited quote and spends nothing; activate requires that exact quote. After a seller rate change, only accept-rates with a fresh quote resumes the campaign.

<file> is a JSON file, or - for standard input, and update replaces a draft with the whole document. The draft names name, daily_cap_mcr, lifetime_cap_mcr (at least the daily cap), flight_start and flight_end (RFC 3339) and networks, one entry per seller network the project joined, each with seller_project_id, screen_ids, slot_ids, creative_ids and optionally venue_types, cities, tags, dayparts and network_cap_mcr. Money fields are decimal mcr strings, never numbers. image_duration_ms (5000 to 30000, ten seconds when omitted) sets how long an image shows, and max_play_price_mcr caps the price of one play; omit it for no ceiling.

A campaign draft takes an optional category from the advertiser category list. Two ads of one category never play in the same ad break on a screen.

preview reads the campaign's current revision unless --expect-rev names one. pause stops new reservations; plays already started finish and settle at their reserved price. resume restarts a manually paused campaign and cannot clear a price-change pause.

Seller: book your own deals for advertisers outside screenRIG on your own screens.

ads direct list
ads direct show <campaign-id>
ads direct create <file>
ads direct update <campaign-id> <file> --expect-rev REVISION
ads direct pause <campaign-id> --expect-rev REVISION
ads direct resume <campaign-id> --expect-rev REVISION
ads direct end <campaign-id> --expect-rev REVISION
ads direct availability <file>
ads direct report <campaign-id> [--from TIME] [--to TIME]
    [--format json|csv|xlsx|pdf] [--output FILE|-]

screenrig ads direct create campaign.json

A draft names name, advertiser, an optional category, flight_start and flight_end, media_ids (1 to 20 of your own ready images or videos), an optional goal_plays, an optional price (model cpm per thousand plays or flat, with an amount and an ISO 4217 currency), an optional image_duration_ms (5000 to 30000, ten seconds when omitted) and targeting: screen_ids, slot_ids, venue_types, cities, tags and dayparts (such as {"days": ["mon"], "start": "11:00", "end": "14:00"}), where an empty list means every opted-in screen or slot. A direct campaign fills an ad break before invited buyers. A goal is paced evenly across the flight and plays first while behind pace; a campaign without a goal takes every eligible slot during its flight. No money moves through screenRIG: you bill the advertiser, and the price values the report.

<file> is a JSON file, or - for standard input. category, here and in a campaign draft, is one of alcohol, apparel, automotive, beauty, cannabis, consumer_electronics, education, entertainment, financial_services, food_and_beverage, gambling, government, grocery, health_and_pharma, home_and_garden, insurance, jobs, legal, media, political, quick_service_restaurants, real_estate, restaurants, retail, sports_and_fitness, technology, telecom, tobacco_and_vaping, travel or utilities. update replaces every writable field, so send the whole document. pause stops a campaign taking ad slots and resume restores it; a goal campaign that fell behind pace while paused plays first until it catches up. end is final: an ended campaign plays no more, cannot be resumed and keeps its report.

availability reads a query with the same targeting and flight and estimates the plays you can still book: the targeted screens' recent ad slot occurrences, less the plays your other direct goals still need. It answers estimated_plays, booked_plays and available_plays, and exclude_campaign_id leaves the campaign you are editing out of booked_plays. A goal above the estimate returns goal_overbooked unless the draft sets "overbook": true.

report lists plays against the goal, pace, value, plays that did not play, and rows by UTC day, screen, slot and media. --from and --to take an RFC 3339 instant, now or an age such as 7d, 12h or 30m, and default to the flight. --format csv, xlsx or pdf writes the rows to --output (default ./direct-report-CAMPAIGN_ID.FORMAT) and answers with its path, bytes and SHA-256; with --format csv, --output - writes the CSV to standard output instead. The CSV columns are day, screen_id, slot_id, media_id, plays, played_ms and estimated_impressions. A JSON or CSV report lists at most 5000 rows and carries the warning direct_report_truncated when more exist: narrow --from and --to for the rest.

Creating, replacing and resuming a direct campaign, availability and report need a plan that includes direct campaigns; other plans are refused with feature_not_in_plan. screenrig project capabilities lists the plan's features.

Seller: approve, reject or request changes to exact submitted creative versions from buyers on review_required.

ads reviews list
ads reviews show <review-id>
ads reviews approve <review-id>
ads reviews reject <review-id> --reason TEXT
ads reviews request-changes <review-id> --note TEXT

screenrig ads reviews request-changes arv_123 --note "Use the new logo"

request-changes sends the buyer your note. To submit the revision, bind the revised media as a new creative, add it to a new campaign, run preview and activate against the fresh quote. The replacement has its own budget and review history. Pause the original campaign before activating its replacement to avoid overlapping delivery. People decide ad creatives in the dashboard's Reviews page, beside playlist and screen changes.

list shows the creative versions awaiting your decision and show one submission with its exact creative. --reason and --note are required and at most 500 characters; the buyer reads them on the creative (ads creatives show). Deciding needs Manage access.

Read spend as a buyer or delivery as a seller.

ads reports spend --campaign-id ID [--format json|csv|xlsx|pdf] [--output FILE]
ads reports delivery --from TIMESTAMP --to TIMESTAMP
    [--format json|csv|xlsx|pdf] [--output FILE]
ads reports fill [--from TIME] [--to TIME] [--format json|csv|xlsx|pdf] [--output FILE]

screenrig ads reports delivery --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z

Delivery reports gross, serving fee and net for the period. A buyer report never shows a seller's other income. fill shows, for up to 35 days, how many ad slot occurrences your screens asked for, how many direct campaigns, invited buyers and your VAST tag filled, and why the rest stayed empty: no_demand, ineligible, separated or capped.

--format csv, xlsx or pdf writes the report as a file to --output (default ./ad-spend.FORMAT, ./ad-delivery.FORMAT or ./ad-fill.FORMAT) and answers with its path, bytes and SHA-256; json is the default and prints the envelope. delivery needs --from and --to as RFC 3339 instants and lists one row per completed occurrence, at most 5000, with truncated set when more exist; the totals cover every settlement. fill takes an RFC 3339 instant, now or an age such as 7d, 12h or 30m: --from defaults to 7 days before --to, --to to now, at most 35 days apart, widened to whole UTC hours.