The command line tool for the Purchasely Management API. Manage apps, placements and experiments from your terminal, CI pipeline or coding agent.
curl -fsSL https://cli.purchasely.io/install.sh | shmacOS and Linux. Needs Node 20 or later.
$ purchasely search "list placements"
[
{
"command": "purchasely placements list --app app_xxx",
"summary": "List placements for an application",
"method": "GET",
"path": "/management/v1/applications/{application_id}/placements",
"scope": "targeting.placements:view"
},
…
]
$ purchasely placements list --app app_xxxOne command installs the CLI under ~/.local/share/purchasely/install and links purchasely into ~/.local/bin or ~/bin. Node 20 or later must be installed first.
curl -fsSL https://cli.purchasely.io/install.sh | shIt downloads the latest version and checks its checksum. It uses ~/.local/bin or ~/bin if one of them is already on your PATH. Else it creates ~/.local/bin and adds one line to your shell profile: ~/.zshrc for zsh, ~/.bashrc and ~/.bash_profile for bash, ~/.profile for other shells. It never uses sudo.
Open a new terminal if the command is not found.
purchasely auth loginCreate the key in the Purchasely Console, from the account menu, in Management API keys. It is not the SDK API key of your app. The CLI asks for the key with a hidden prompt and stores it in the macOS keychain, or in a file only you can read on Linux.
purchasely auth status shows where the key comes from and its last 4 characters. It does not test API access.
purchasely apps list --output tableIt prints your applications with their ids. Use an id as --app in every Management command. In CI, set PURCHASELY_API_KEY as a secret instead of logging in.
Remove the install folder and the purchasely link in your bin folder. command -v purchasely shows the link.
rm -rf ~/.local/share/purchasely/install
rm "$(command -v purchasely)"Replace app_xxx and the other ids with your own. purchasely apps list gives your application ids.
purchasely placements list \
--app app_xxx \
--fields id,vendor_id \
| jq -r '.placements[]
| "\(.id) \(.vendor_id)"'The pipe requires jq. Without --app, the command lists the placements of all your apps.
purchasely placements get \
--app app_xxx --id plc_xxx \
--output tableA read: it changes nothing and needs no --env.
Look at the request first. The dry run sends nothing.
purchasely placements update \
--app app_xxx --id plc_xxx \
--data '{"name":"Onboarding"}' \
--env staging --dry-runThen send it.
purchasely placements update \
--app app_xxx --id plc_xxx \
--data '{"name":"Onboarding"}' \
--env stagingThe commands are built from the Management API spec. When the API gets a new endpoint, the CLI gets a new command. The pattern is always purchasely <resource> <action>.
Screen commands manage metadata. They do not return screen layout JSON.
jq. Errors go to stderr as one JSON object. Add --output table to read a list yourself. An answer over 200 KB goes to a file and the CLI prints its path.purchasely dashboard summary --app app_xxx --output table shows the MRR, active subscriptions, paywall viewers and conversions of an app, with a sparkline per metric. Without --output table, the same numbers come as JSON.purchasely search "start an a/b test" returns the best matching commands. --help on a command shows its scope, path, options and an example.man purchasely. Agents read it as JSON with purchasely reference --format json.purchasely api GET /applications calls any Management endpoint with your key, under the same rules: the limiter, --dry-run, --env on a write and the confirmation.source <(purchasely completion zsh) in your ~/.zshrc completes the commands and the options. Bash and fish work too.purchasely games opens six terminal games: 2048, invaders, minesweeper, pong, snake and tetris. They use no key and send no request.--dry-run prints the method, URL, headers and body, and sends nothing. The key shows as <redacted>. It works without a key.--env prod or --env staging. Reads use prod by default. A write without --env is refused, also with --dry-run.--yes confirms. In a script, it stops with exit code 8 and gives a token that you can send back with --confirm-token within 5 minutes.Management commands go to api.purchasely.io, or api-staging.purchasely.io with --env staging, with your key. The User-Agent header carries the CLI version and your --reason value.
Once a day, the CLI asks cli.purchasely.io for the latest version and downloads it from there. purchasely ai downloads the public Purchasely AI plugin from GitHub.
| 0 | Success |
| 1 | Generic error, network error, server error |
| 2 | Usage error: bad flag or bad JSON in --data |
| 3 | No key, or key not accepted |
| 4 | Forbidden: missing scope or feature |
| 5 | Validation failed |
| 6 | Not found |
| 7 | Rate limited: stop and wait |
| 8 | Confirmation required and not given |
| 10 | Write refused: --env missing |
Claude Code, Codex and other agents can drive the CLI safely. Give them these rules.
purchasely search "<task>". The first result is the best match.purchasely <resource> <action> --help.--dry-run before every write and show the request to the user. Use --env staging unless the user says prod.--yes without the approval of the user.Give the agent the key through PURCHASELY_API_KEY or purchasely auth login. Never put the key in a command.
# User: rename the onboarding placement on staging
$ purchasely search "update a placement"
[
{
"command": "purchasely placements update --app app_xxx --id <id> --data @body.json --env prod",
"method": "PATCH",
…
}
]
$ purchasely placements update --help
$ purchasely placements update --app app_xxx --id plc_xxx \
--data '{"name":"Onboarding"}' --env staging --dry-run
{
"method": "PATCH",
"url": "https://api-staging.purchasely.io/management/v1/applications/app_xxx/placements/plc_xxx",
"headers": {
"Authorization": "Bearer <redacted>",
"Accept": "application/json",
"User-Agent": "purchasely-cli/<version> (-; -)",
"Content-Type": "application/json"
},
"body": {
"name": "Onboarding"
}
}
# Agent: this is the request. Send it?
# User: yes
$ purchasely placements update --app app_xxx --id plc_xxx \
--data '{"name":"Onboarding"}' --env stagingThe rules above make the CLI safe for any agent. The plugin adds Purchasely knowledge to the agent: SDK integration, review, debug and migration.
purchasely ai install--agent to choose one.purchasely ai status shows the agents and the plugin version. purchasely ai update and purchasely ai uninstall change only what ai install registered.purchasely-cli, sdk-expert, integrate, review, debug and migrate.
Ask the agent to integrate the SDK with your real placements, products, plans and custom events, read by the CLI from your account. Ask it to debug, review or improve your integration.
The CLI does not return the SDK API key of an app. Copy it from the Console (App settings) into your app configuration. The agent does not ask for it.
The CLI keeps itself up to date. You do not need to run the installer again.
Once a day, the CLI checks for a new version in the background. It downloads and installs it in a separate process, so your command does not wait. The new version is used on the next run.
purchasely updateChecks and installs the latest version at once.
export PURCHASELY_DISABLE_AUTOUPDATE=1The automatic check also stays off when the CI variable is set, so a pipeline always runs the version it installed.