Launches commands

Every command is one API operation, named by its operationId. Global flags such as --output and --api-url work on all of them, see CLI commands.

add-ads

Add ads. POST /v1/brands/{brandId}/launches/{launchId}/ads, API reference.

koast add-ads --brand <brand> --launch-id <launch-id> --ads <ads> [--json <file|->]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--ads`	JSON object, repeatable	Yes	Ads to create (1-100). Each entry targets a specific adsetNodeId with optional creativeId and copyGenerationId. At least 1 item, at most 100 items.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast add-ads --brand 123 --launch-id LAUNCH_ID --json body.json

With body.json:

{
  "ads": [
    {
      "adsetNodeId": "string",
      "name": "string",
      "creativeId": 12.5,
      "copyGenerationId": 12.5
    }
  ]
}

add-adset

Add ad set. POST /v1/brands/{brandId}/launches/{launchId}/ad-sets, API reference.

koast add-adset --brand <brand> --launch-id <launch-id> --campaign-node-id <campaign-node-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--campaign-node-id`	string	Yes	ID of the campaign node to add the ad set to
`--name`	string	No	Name for the new ad set
`--settings`	JSON object	No	Optional settings to apply at create time. Dot-notation paths, same shape as updateSettings (e.g. `targeting.ageRange`, `budget.dailyAmount`, `schedule.startTime`, `optimization.bidStrategy`). budget.dailyAmount / budget.lifetimeAmount are CENTS. Array-typed paths must be native arrays. The response reports `appliedSettings` and `notApplied`, do NOT claim any value the response did not echo back.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast add-adset --brand 123 --launch-id LAUNCH_ID --campaign-node-id CAMPAIGN_NODE_ID

add-campaign

Add campaign. POST /v1/brands/{brandId}/launches/{launchId}/campaigns, API reference.

koast add-campaign --brand <brand> --launch-id <launch-id> --name <name> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--name`	string	Yes	Name for the new campaign. At most 500 characters.
`--objective`	string	No	Campaign objective. Must be one of: 'website-conversions', 'lead-form', 'traffic'. These are Koast-side canonical values, DO NOT pass Meta-native objective enum names like OUTCOME_SALES or OUTCOME_LEADS. One of `website-conversions`, `lead-form`, `traffic`.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast add-campaign --brand 123 --launch-id LAUNCH_ID --name NAME

apply-snapshot-template

Apply campaign snapshot template. POST /v1/brands/{brandId}/launches/{launchId}/snapshot-templates/{templateId}/apply, API reference.

koast apply-snapshot-template --brand <brand> --launch-id <launch-id> --template-id <template-id>

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--template-id`	string	Yes	ID of the template to apply

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one.

Example:

koast apply-snapshot-template --brand 123 --launch-id LAUNCH_ID --template-id TEMPLATE_ID

apply-structure-template

Apply structure template. POST /v1/brands/{brandId}/launches/{launchId}/structure-templates/{templateId}/apply, API reference.

koast apply-structure-template --brand <brand> --launch-id <launch-id> --template-id <template-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--template-id`	string	Yes	Structure template ID. Omit to read the template currently open in the builder from the Current Context block. Pass an explicit id only when acting on a different template than the one in scope.
`--overwrite`	boolean	No
`--supplied-deferred`	JSON object	No	Per-account deferred values keyed by adAccountId, supplied at apply.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast apply-structure-template --brand 123 --launch-id LAUNCH_ID --template-id TEMPLATE_ID

attach-lead-form

Attach lead form. POST /v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetNodeId}/lead-form, API reference.

koast attach-lead-form --brand <brand> --launch-id <launch-id> --adset-node-id <adset-node-id> --lead-form-id <lead-form-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--adset-node-id`	string	Yes	Koast adset node id to attach the lead form to.
`--lead-form-id`	string	Yes	Meta lead form id from listLeadForms.
`--lead-form-name`	string	No	Optional human name of the lead form (from listLeadForms).

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast attach-lead-form --brand 123 --launch-id LAUNCH_ID --adset-node-id ADSET_NODE_ID --lead-form-id LEAD_FORM_ID

clone-live-campaign

Clone live campaign. POST /v1/brands/{brandId}/launches/clone, API reference.

koast clone-live-campaign --brand <brand> --provider-campaign-id <provider-campaign-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--provider-campaign-id`	string	Yes	Campaign id to clone on the ad platform (the raw `id` from listAccountCampaigns rows).
`--count`	integer	No	How many cloned batches to create (1 batch per clone, max 20). Default `1`. Minimum 1, maximum 20.
`--title-prefix`	string	No	Optional title prefix for the cloned batches; a copy index is appended when count > 1. At most 180 characters.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast clone-live-campaign --brand 123 --provider-campaign-id PROVIDER_CAMPAIGN_ID

compute-creative-fatigue

Compute creative fatigue. GET /v1/brands/{brandId}/launches/{launchId}/creative-fatigue, API reference.

koast compute-creative-fatigue --brand <brand> --launch-id <launch-id> [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--ad-id`	string	No	Optional ad-platform ad id to score a single ad. When omitted, scores the aggregated series at the chosen level.
`--level`	string	No	Insight level; defaults to 'ad' since fatigue is a per-creative concept. One of `campaign`, `adset`, `ad`. Default `"ad"`.
`--days`	integer	No	Lookback window in days. Defaults to 30. Default `30`. Minimum 3, maximum 90.

Required scope: read.

Example:

koast compute-creative-fatigue --brand 123 --launch-id LAUNCH_ID

create-campaign-launch

Create campaign launch. POST /v1/brands/{brandId}/launches, API reference.

koast create-campaign-launch --brand <brand> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--title`	string	No	Optional human title; defaults to "Untitled Batch" server-side. At most 200 characters.
`--description`	string	No	At most 2000 characters.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast create-campaign-launch --brand 123

delete-batch

Delete batch or pipeline card. DELETE /v1/brands/{brandId}/launches/{launchId}, API reference.

koast delete-batch --brand <brand> --launch-id <launch-id>

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.

Required scope: write.

Example:

koast delete-batch --brand 123 --launch-id LAUNCH_ID

distribute-creative

Distribute creative. POST /v1/brands/{brandId}/launches/{launchId}/creatives/distribute, API reference.

koast distribute-creative --brand <brand> --launch-id <launch-id> --creative-id <creative-id> --targets <targets> --strategy <strategy> [--json <file|->]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--creative-id`	integer	Yes
`--targets`	JSON object	Yes
`--strategy`	string	Yes	One of `newAdPerTarget`, `replaceFirstAd`.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast distribute-creative --brand 123 --launch-id LAUNCH_ID --json body.json

With body.json:

{
  "creativeId": 1,
  "targets": {
    "adsetIds": [
      "string"
    ],
    "campaignIds": [
      "string"
    ]
  },
  "strategy": "newAdPerTarget"
}

duplicate-and-vary

Duplicate and vary. POST /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/variations, API reference.

koast duplicate-and-vary --brand <brand> --launch-id <launch-id> --node-id <node-id> --count <count> --vary <vary> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--node-id`	string	Yes	ID of the node to duplicate
`--count`	number	Yes	Minimum 1, maximum 20.
`--vary`	JSON object	Yes
`--name-template`	string	No	Optional name template, e.g., "{original} - Variant {i}"

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast duplicate-and-vary --brand 123 --launch-id LAUNCH_ID --node-id NODE_ID --json body.json

With body.json:

{
  "count": 12.5,
  "vary": {
    "path": "string",
    "values": [
      null
    ]
  },
  "nameTemplate": "string"
}

duplicate-node

Duplicate ad set or ad. POST /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/duplicate, API reference.

koast duplicate-node --brand <brand> --launch-id <launch-id> --node-id <node-id> --node-type <node-type> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--node-id`	string	Yes	ID of the node to duplicate
`--node-type`	string	Yes	Type of the node to duplicate. One of `adset`, `ad`.
`--count`	number	No	Number of copies to create (default 1, max 50). Default `1`. Minimum 1, maximum 50.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast duplicate-node --brand 123 --launch-id LAUNCH_ID --node-id NODE_ID --node-type adset

edit-live-campaign

Edit live campaign budget. POST /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/live-budget, API reference.

koast edit-live-campaign --brand <brand> --launch-id <launch-id> --node-id <node-id> --level <level> --budget-type <budget-type> --amount <amount> [--json <file|->]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--node-id`	string	Yes	ID of the live campaign or ad set node to edit
`--level`	string	Yes	Level of the node. Budget cannot be edited on an ad. One of `CAMPAIGN`, `ADSET`.
`--budget-type`	string	Yes	Whether to set the daily or lifetime budget. One of `daily`, `lifetime`.
`--amount`	integer	Yes	New budget in CENTS (5000 = $50.00). Minimum 100 ($1.00). If the user said "$50", pass 5000. Minimum 100, maximum 10000000.

Required scope: publish. Sends an Idempotency-Key, which the API requires here. The CLI generates one and prints it to stderr. Pass --idempotency-key to reuse a key on a retry. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast edit-live-campaign --brand 123 --launch-id LAUNCH_ID --node-id NODE_ID --level CAMPAIGN --budget-type daily --amount 1

get-ad-delivery-status

Get ad delivery status. GET /v1/brands/{brandId}/launches/{launchId}/delivery-status, API reference.

koast get-ad-delivery-status --brand <brand> --launch-id <launch-id>

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.

Required scope: read.

Example:

koast get-ad-delivery-status --brand 123 --launch-id LAUNCH_ID

get-ad-details

Get ad details. GET /v1/brands/{brandId}/launches/{launchId}/ads/{adId}, API reference.

koast get-ad-details --brand <brand> --launch-id <launch-id> --ad-id <ad-id>

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--ad-id`	string	Yes	ID of the ad to get details for

Required scope: read.

Example:

koast get-ad-details --brand 123 --launch-id LAUNCH_ID --ad-id AD_ID

get-adset-details

Get ad set details. GET /v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetId}, API reference.

koast get-adset-details --brand <brand> --launch-id <launch-id> --adset-id <adset-id>

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--adset-id`	string	Yes	ID of the ad set to get details for

Required scope: read.

Example:

koast get-adset-details --brand 123 --launch-id LAUNCH_ID --adset-id ADSET_ID

get-campaign-tree

Get campaign tree. GET /v1/brands/{brandId}/launches/{launchId}/tree, API reference.

koast get-campaign-tree --brand <brand> --launch-id <launch-id>

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.

Required scope: read.

Example:

koast get-campaign-tree --brand 123 --launch-id LAUNCH_ID

get-insights-daily

Get daily insights. GET /v1/brands/{brandId}/launches/{launchId}/insights/daily, API reference.

koast get-insights-daily --brand <brand> --launch-id <launch-id> [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--level`	string	No	One of `campaign`, `adset`, `ad`. Default `"campaign"`.
`--days`	number	No	Default `30`. Minimum 1, maximum 90.
`--start-date`	string	No	Explicit window start (YYYY-MM-DD). Pass BOTH startDate and endDate to fetch an exact date range instead of the relative `days` window, use this when the user names specific dates so the year is never guessed.
`--end-date`	string	No	Explicit window end (YYYY-MM-DD). Pass together with startDate; overrides `days`.

Required scope: read.

Example:

koast get-insights-daily --brand 123 --launch-id LAUNCH_ID

get-metrics

Get metrics. GET /v1/brands/{brandId}/launches/{launchId}/metrics, API reference.

koast get-metrics --brand <brand> --launch-id <launch-id> --level <level> [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--level`	string	Yes	Which level to pull metrics at. One of `campaign`, `adset`, `ad`.
`--date-preset`	string	No	Reporting date preset. If omitted, defaults to today. Use last_7d / last_28d / last_30d / last_90d / this_month / last_month as needed. Every last_Nd preset ENDS YESTERDAY and does not include today, so a campaign that only started yesterday reads as zero under last_7d, use today or yesterday to see it, and say which window a number came from. For "lifetime" / "all time" / "since launch", use maximum, NOT "lifetime" (it is not an accepted value). Arbitrary start/end date ranges are not supported by the backend. One of `today`, `yesterday`, `this_week_sun_today`, `last_7d`, `last_14d`, `last_28d`, `last_30d`, `last_90d`, `this_month`, `last_month`, `maximum`.
`--id`	string	No	Optional entity id to scope to. Omit for all entities at this level.

Required scope: read.

Example:

koast get-metrics --brand 123 --launch-id LAUNCH_ID --level campaign

get-settings

Get settings. GET /v1/brands/{brandId}/launches/{launchId}/settings, API reference.

koast get-settings --brand <brand> --launch-id <launch-id> [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--node-id`	string	No	ID of the node (single-node form; omit when using `nodes`)
`--node-type`	string	No	Type of the node (single-node form). One of `campaign`, `adset`, `ad`.

Required scope: read.

Example:

koast get-settings --brand 123 --launch-id LAUNCH_ID

get-targeting-options

Get targeting options. GET /v1/brands/{brandId}/launches/{launchId}/targeting-options, API reference.

koast get-targeting-options --brand <brand> --launch-id <launch-id> [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--query`	string	No	Search query to filter targeting options

Required scope: read.

Example:

koast get-targeting-options --brand 123 --launch-id LAUNCH_ID

import-campaigns

Import campaigns. POST /v1/brands/{brandId}/launches/{launchId}/campaigns/import, API reference.

koast import-campaigns --brand <brand> --launch-id <launch-id> --campaign-ids <campaign-ids> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--campaign-ids`	string, repeatable	Yes	Ad-platform campaign IDs to import (non-empty). At least 1 item, at most 1 items.
`--source-type`	string	No	'existing' attaches to the live campaign (keeps its ad-platform IDs). 'duplicate' copies it as an editable draft with ad-platform IDs stripped, prefer cloneLiveCampaign for that. Anything else is rejected by the API. One of `existing`, `duplicate`. Default `"existing"`.
`--source-ad-account-id`	string	No	Ad account id to import FROM (e.g. act_1234 on Meta), when it differs from the batch's own ad account. Get it from listMyAdAccounts, never invent it. Omit for a same-account import. The brand must already have a connected credential for this account; if it does not, the API refuses and this tool reports the refusal instead of importing.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast import-campaigns --brand 123 --launch-id LAUNCH_ID --campaign-ids CAMPAIGN_IDS

import-live-campaign

Import live campaign. POST /v1/brands/{brandId}/launches/import, API reference.

koast import-live-campaign --brand <brand> --provider-campaign-id <provider-campaign-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--provider-campaign-id`	string	Yes	Campaign id on the ad platform (the raw `id` from listAccountCampaigns rows).
`--title`	string	No	Optional batch title; defaults to the campaign name server-side. At most 200 characters.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast import-live-campaign --brand 123 --provider-campaign-id PROVIDER_CAMPAIGN_ID

launch-campaign

Launch campaign. POST /v1/brands/{brandId}/launches/{launchId}/publish, API reference.

koast launch-campaign --brand <brand> --launch-id <launch-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--confirm`	boolean	No	Set true ONLY after the user has explicitly authorized publishing on a prior turn. When false or omitted, the tool returns a preview and asks for confirmation, it does NOT publish.

Example:

koast launch-campaign --brand 123 --launch-id LAUNCH_ID

list-koast-batches

List Koast batches. GET /v1/brands/{brandId}/launches, API reference.

koast list-koast-batches --brand <brand> [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--account-id`	string	No	Ad account id (act_xxx on Meta). Optional, defaults to current page context.
`--status`	string	No	Filter by lifecycle status. One of `DRAFT`, `IMPORTED`, `PENDING`, `RUNNING`, `COMPLETED`, `COMPLETED_WITH_ISSUES`, `ACTION_REQUIRED`, `FAILED`, `CANCELLED`.
`--search`	string	No	Substring match on batch title.
`--page`	integer	No	Default `1`.
`--limit`	integer	No	Page size. Default `50`. Minimum 1, maximum 100.
`--cursor`	string	No	Opaque cursor from the previous page's `nextCursor`. Omit for the first page.

Required scope: read. Paged. --all follows nextCursor to the end and prints one JSON line per item.

Example:

koast list-koast-batches --brand 123

remove-nodes

Remove items from campaign tree. POST /v1/brands/{brandId}/launches/{launchId}/nodes/remove, API reference.

koast remove-nodes --brand <brand> --launch-id <launch-id> --nodes <nodes> [--json <file|->]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--nodes`	JSON object, repeatable	Yes	Nodes to delete (1-200). Each entry names its nodeId and nodeType. At least 1 item, at most 200 items.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast remove-nodes --brand 123 --launch-id LAUNCH_ID --json body.json

With body.json:

{
  "nodes": [
    {
      "nodeId": "string",
      "nodeType": "campaign"
    }
  ]
}

rename-node

Rename campaign, ad set or ad. POST /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}/rename, API reference.

koast rename-node --brand <brand> --launch-id <launch-id> --node-id <node-id> --new-name <new-name> [--json <file|->]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--node-id`	string	Yes	ID of the node to rename
`--new-name`	string	Yes	New name for the node (must be non-empty). At most 500 characters.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast rename-node --brand 123 --launch-id LAUNCH_ID --node-id NODE_ID --new-name NEW_NAME

save-campaign-snapshot

Save campaign snapshot template. POST /v1/brands/{brandId}/launches/{launchId}/snapshot-templates, API reference.

koast save-campaign-snapshot --brand <brand> --launch-id <launch-id> --name <name> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--name`	string	Yes	Name for the template (non-empty). At most 191 characters.
`--description`	string	No	Description of what this template is for. At most 191 characters.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast save-campaign-snapshot --brand 123 --launch-id LAUNCH_ID --name NAME

swap-creatives

Swap creatives. POST /v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetNodeId}/creatives/swap, API reference.

koast swap-creatives --brand <brand> --launch-id <launch-id> --adset-node-id <adset-node-id> --creative-ids <creative-ids> [--json <file|->]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--adset-node-id`	string	Yes	Koast adset node id whose ads should carry the new creatives.
`--creative-ids`	number, repeatable	Yes	Numeric creative IDs to place on the ad set, in order. Copy on existing ads is preserved. At least 1 item, at most 100 items.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast swap-creatives --brand 123 --launch-id LAUNCH_ID --adset-node-id ADSET_NODE_ID --creative-ids 1

turn-launch-into-template

Turn launch into structure template. POST /v1/brands/{brandId}/launches/{launchId}/structure-templates, API reference.

koast turn-launch-into-template --brand <brand> --launch-id <launch-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--name`	string	No	At most 191 characters.

Required scope: write. Accepts --idempotency-key. The CLI sends a key only when you give one. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast turn-launch-into-template --brand 123 --launch-id LAUNCH_ID

update-node

Update campaign, ad set or ad. PATCH /v1/brands/{brandId}/launches/{launchId}/nodes/{nodeId}, API reference.

koast update-node --brand <brand> --launch-id <launch-id> --node-id <node-id> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--node-id`	string	Yes	ID of the node to update
`--creative-id`	number	No	Numeric creative ID to attach to an ad node. Use this when the user says "use this creative" or selects a creative from the attachments panel.
`--copy-generation-id`	number	No	Numeric copy generation ID to attach to an ad node. Use this AFTER calling generateCopy, take the returned id and pass it here on the target ad.
`--post-id`	string	No	Existing Meta post ID to attach to an ad node.
`--properties`	JSON object	No	Other key-value pairs to update (e.g., { name: "New name" }). Do NOT put creativeId / copyGenerationId / postId here, use the dedicated fields above.

Required scope: write. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast update-node --brand 123 --launch-id LAUNCH_ID --node-id NODE_ID

update-settings

Update settings. PATCH /v1/brands/{brandId}/launches/{launchId}/settings, API reference.

koast update-settings --brand <brand> --launch-id <launch-id> --node-ids <node-ids> --node-type <node-type> [--json <file|->] [flags]

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.
`--node-ids`	string, repeatable	Yes	IDs of the nodes to update (one or more). At least 1 item.
`--node-type`	string	Yes	Type of the nodes (all nodeIds must share this level). One of `campaign`, `adset`, `ad`.
`--settings`	JSON object	No	Key-value pairs where keys are dot-notation setting paths and values are the new values. budget.dailyAmount and budget.lifetimeAmount are CENTS (e.g., 5000 = $50.00). optimization.bidAmount, budget.adSetMinimumSpend, budget.adSetMaximumSpend are DOLLARS. Array-typed paths (targeting.ageRange, targeting.interests, targeting.locations, targeting.excludedLocations, targeting.locales, placements.devices) MUST be native JSON arrays, not strings. `isCBO` is NOT allowed here, use `budgetStrategy`.
`--budget-strategy`	string	No	The ONLY way to change Campaign Budget Optimization. Set "CBO" (campaign-level budget) or "ABO" (ad-set-level budget) ONLY when the user explicitly asked to switch budget optimization. Omit to leave it unchanged. Never put `isCBO` inside `settings`. One of `CBO`, `ABO`.

Required scope: write. --json <file|-> supplies the whole body. Body flags are applied over it.

Example:

koast update-settings --brand 123 --launch-id LAUNCH_ID --node-ids NODE_IDS --node-type campaign

validate-launch

Validate launch. GET /v1/brands/{brandId}/launches/{launchId}/validation, API reference.

koast validate-launch --brand <brand> --launch-id <launch-id>

Flag	Type	Required	Description
`--brand`	integer	Yes	The brand the request acts on. Every brand-scoped resource lives under its brand.
`--launch-id`	string	Yes	The campaign launch (batch) id.

Required scope: read.

Example:

koast validate-launch --brand 123 --launch-id LAUNCH_ID

Launches commands

On this page