---
title: amp guides
description: "Reference for amp guides list, get, create, update, and archive, which manage draft in-app guides."
product: general
lang: en
last_updated: 2026-11-18
token_estimate: 1848
---
# amp guides

`amp guides` manages guides: in-app tours, modals, banners, and tooltips. Read commands require `guides:read`; create, update, and archive require `guides:write`. Publish and schedule guides in Amplitude.

## `amp guides list`

Returns guides in the project. Results use the standard Developer API list envelope with cursor pagination (`cursor`, `limit`).

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Full-text search (`q`) and custom sort orders are not supported yet.

```bash
amp guides list --project <project_id> --limit 10
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--cursor` | string | No | Opaque cursor from `pagination.next_cursor` on the previous response. Numeric offsets are capped by the underlying search index (10,000 results per query). Well-formed pagination stops before that window; requests whose cursor would exceed it return 400 `pagination_not_supported`. Alias: `--next-cursor`. |
| `--limit` | integer | No | Number of items to return. Defaults to 50, max 200. |
| `--platform` | string | No |  |
| `--created-after` | string | No |  |
| `--created-before` | string | No |  |
| `--created-by` | string | No | Filter by creator email or login id (exact match). |
| `--include-archived` | boolean | No |  |

Requires the `guides:read` scope.

## `amp guides get`

Get guide.

```bash
amp guides get --project <project_id> --guide <guide_id> --include-unpublished-changes
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--guide` | string | Yes | Guide (tour nudge) identifier. Alias: `--guide-id`. |
| `--include-unpublished-changes` | boolean | No | When true, return the latest draft (unpublished edits) when one exists. Default false returns the live published guide. |

Requires the `guides:read` scope.

## `amp guides create`

Creates an unpublished draft guide. Publish, schedule, and test instrumentation are not available via API in v1. At most one content variant is accepted on create; the `control` key is reserved.

```bash
amp guides create --project <project_id> --title "Welcome tour"
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--title` | string | Yes |  |
| `--description` | string | No |  |
| `--platform` | string: `web`, `ios`, `android`, `react-native`, `desktop`, `flutter` | No | Target platform. Guides and surveys without an explicit platform are returned as `web`. |
| `--priority` | integer | No |  |
| `--variants` | array | No | JSON array, or a comma-separated list for strings. |

Requires the `guides:write` scope.

## `amp guides update`

Updates metadata, targeting, and content variants. For published guides, changes apply to a draft until publish in the UI. `latest_version` is required and must match the current draft, otherwise the update returns `409`. The check runs before the write rather than atomically with it, so it reduces but does not fully prevent lost updates from concurrent writers. Publish, schedule, and test instrumentation are not available via API in v1. Status fields on the response are derived read-only. When `variants` is sent, it must list every existing variant by `id` with its unchanged `variant` key; steps within a variant can be added, edited, reordered, or removed. `tags` is not writable in v1 and returns `400`.

```bash
amp guides update --project <project_id> --guide <guide_id> --latest-version <version> --title "Welcome tour v2"
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--guide` | string | Yes | Guide (tour nudge) identifier. Alias: `--guide-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--title` | string | No |  |
| `--description` | string | No |  |
| `--platform` | string: `web`, `ios`, `android`, `react-native`, `desktop`, `flutter` | No | Target platform. Guides and surveys without an explicit platform are returned as `web`. |
| `--priority` | integer | No |  |
| `--page-target-segments` | array | No | Pages where the guide is eligible. Empty means every page. Each item uses camelCase keys. JSON array, or a comma-separated list for strings. |
| `--temporarily-hide-page-target-segments` | array | No | Page rules that are saved but not currently applied. JSON array, or a comma-separated list for strings. |
| `--hide-if-page-targeting-not-met` | boolean | No |  |
| `--trigger-config` | object | No | When the guide or survey appears. One trigger, or an array of triggers where any match fires it. Nested keys keep their stored names (`selector`, `event`, `event_count`, `delay`). Optional `filters` and `sessionPropertyFilters` are accepted and passed through. |
| `--lifecycle` | object | No | How often the guide or survey may show again. `periodCount` is camelCase; the other keys are snake\_case. |
| `--dismissible` | boolean | No |  |
| `--snoozable` | boolean | No |  |
| `--snoozable-on-all-steps` | boolean | No |  |
| `--snooze-duration` | object | No | How long a snooze lasts. |
| `--snooze-label` | string | No |  |
| `--template-source` | string | No |  |
| `--show-step-counter` | boolean | No |  |
| `--step-counter-format` | string | No |  |
| `--tags` | array | No | JSON array, or a comma-separated list for strings. |
| `--variants` | array | No | JSON array, or a comma-separated list for strings. |
| `--latest-version` | integer | Yes | Expected `latest_version` from the last GET with `include_unpublished_changes=true`. |

Requires the `guides:write` scope.

## `amp guides archive`

Archives an unpublished guide. A guide counts as published while its flag is enabled, unless it's only in test mode without a schedule; archiving a published guide returns `409` with `error_code: cannot_archive_published`. Unpublish it in Amplitude first. Use `dry_run=true` to check whether a guide can be archived. An already archived guide returns `404`, like `GET`.

Requires --yes to apply changes, or --dry-run when supported to validate without applying changes.

```bash
amp guides archive --project <project_id> --guide <guide_id> --dry-run
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--guide` | string | Yes | Guide (tour nudge) identifier. Alias: `--guide-id`. |
| `--dry-run` | boolean | No | Validate request without performing mutation. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |

Requires the `guides:write` scope.

