Automation & Integrations

Use the Sequence CLI

Install and use the Sequence CLI to edit projects, run app jobs, transcribe media, and automate workflows from Terminal or structured JSON.

What the CLI is for

The Sequence command-line interface is named sq. Use it to transcribe or inspect media, import files, query projects and transcripts, edit variants, monitor jobs, or produce machine-readable JSON.

Commands are separated by ownership:

Local commands such as sq info, sq hash, and sq transcribe do not modify the Sequence library.
Commands under sq app work with app-managed data and may read or modify your Sequence library.

Compatibility

The app and CLI are independently versioned. This guide follows the implemented Automation contract; commands available to you depend on both installed components. The CLI requires an Apple Silicon Mac running macOS 15 or later. App and CLI version numbers do not need to match; compatibility is checked through the app connection.

App-backed workflows require Sequence to be open, signed in, activated, and showing the main workspace, with Settings → Automation → Enable Automation turned on. If App Lock is enabled, unlock Sequence before running protected commands.

Check the installed CLI and connection with sq --version and sq app doctor. If a command or protocol is unsupported, update the CLI and app before retrying. Standalone commands do not require an open library.

Install with Homebrew

Install the current CLI release from the official Sequence formula:

brew install rockstarsunlimited/sequence/sequence
sq app connect

The sequence formula is installed by its fully qualified tap path so Homebrew does not need a separate tap command.

In Sequence, Settings → Automation → Command Line Interface shows the installation status and provides a Copy button for the Homebrew install-and-connect command. Wait for the status to show Connected before setting up an assistant.

Update it later with:

brew update
brew upgrade sequence
sq --version
sq app doctor

Get help and shell completions

Show the command overview or detailed help for a command:

sq --help
sq transcribe --help
sq app --help
sq app projects --help

Generate completions for Zsh, Bash, or Fish. For example, to enable Zsh completions for the current shell:

source <(sq completions zsh)

To keep completions enabled, save the generated script in the appropriate completions directory for your shell.

Inspect media

Probe a media file without importing it into the library:

sq info /path/to/media.mov
sq info /path/to/media.mov --json

Compute Sequence's duplicate-detection hash, or use its quick path-resolution hash:

sq hash /path/to/media.mov
sq hash /path/to/media.mov --quick --json

These are Sequence media-identification hashes, not whole-file SHA-256 checksums. The default hashes the file size and sampled head/tail content; --quick uses smaller first/last chunks and the file size.

Work with the Sequence library

Commands that use the Sequence library are grouped under sq app. Check that the app, authorization, database, broker, and bundled media tools are ready:

sq app doctor
sq app doctor --json

If Sequence asks you to associate a CLI installation with the app, open Sequence and run:

sq app connect

You can also inspect the local app broker directly with sq app broker status --json.

List Catalogs and use the returned stable ID to filter projects:

sq app catalogs list
sq app catalogs list --include-system --json
sq app projects list --catalog <catalog-id> --json

List projects with optional pagination. The default page starts at offset 0 and contains up to 50 projects:

sq app projects list
sq app projects list --limit 50 --offset 0 --json

Search a transcript or read a time range:

sq app transcript search <project-id> "search phrase"
sq app transcript search <project-id> "search phrase" --include-hidden --json
sq app transcript range <project-id> <start-seconds> <end-seconds> --json

Page through stable sentence IDs, including hidden sentences when needed for an edit plan. The default limit is 100; --limit accepts 1 through 500:

sq app transcript sentences list <project-id> --offset 0 --limit 100 --json
sq app transcript sentences list <project-id> --include-hidden --json

List transcript-derived keywords:

sq app keywords list <project-id>
sq app keywords list <project-id> --include-unapproved --json

Use IDs returned by sq app projects list rather than project names in commands that require a project ID.

Add and inspect markers

List a project's timeline markers or add a marker at a time in seconds:

sq app markers list <project-id> --json
sq app markers add <project-id> 42.5 --name "Select begins" --confirm --json

Adding a marker changes the project and therefore requires --confirm. The app refreshes its visible project state after broker-backed edits.

Create variants and edit plans

You can ask an automation agent to inspect an existing variant, create a named sibling variant, remove words or sentences, and reorder complete sentences. The finished variant is persisted directly in Sequence and appears in the app like any variant you create manually.

For example:

Use sq to inspect my “Best Cut” variant, create a new variant named “Agent Pass,” remove unnecessary words and sentences, reorder sentences where useful, and leave the original untouched. Preview and validate the plan first, then apply it.

An agent can discover the project and sentence IDs, generate an edit plan, preview it, and submit it. You do not need to save or import a JSON file manually.

To duplicate a project without sentence edits, use:

sq app variants create <project-id> --name "Agent Cut" --confirm --json

variants create and create-from-plan create ordinary child variants, not copies of group-owned programs. For a program-copy workflow, use the edit-session tools described in the MCP guide.

For a sentence-level agent pass, create-from-plan atomically duplicates the chosen source variant, applies sentence visibility and ordering changes, and names the new sibling. The original source, for example “Best Cut”, remains unchanged.

The plan uses stable IDs returned by sq app transcript sentences list:

{
  "name": "Agent Cut, concise",
  "includedSentenceIds": ["sentence-a", "sentence-c"],
  "sentenceOrder": ["sentence-c", "sentence-a"]
}

An agent will normally send this JSON through standard input. The commands it invokes are:

sq app variants preview-plan <best-cut-project-id> --plan - --json
sq app variants create-from-plan <best-cut-project-id> --plan - --confirm --json

You can still pass a saved file such as --plan ./variant-plan.json when that is useful for a reproducible workflow. includedSentenceIds selects which sentences remain visible. If supplied, sentenceOrder must contain exactly the same IDs in the required edited order. Previewing reports validation, projected visibility and ordering, exclusions, and copied marker counts without writing. Creation is transactional: if validation or persistence fails, no partial variant is created.

The successful create-from-plan --json envelope contains the new variant's ID in result.id. Sentence-group IDs remain stable for the plan, but copied words receive new IDs. Before making word-level edits, inspect the new variant's transcript using the returned project ID, collect its word IDs, and then disable those words on “Agent Pass” without affecting “Best Cut”:

sq app transcript words disable <new-variant-id> <word-id>... --confirm --json

When Sequence is running, sq uses the app broker and publishes a Catalog refresh after creating the variant. The new sibling should appear in the app without importing JSON or manually refreshing the library, although Sequence does not necessarily switch to the new variant automatically.

--confirm authorizes commands that explicitly require confirmation, including variant creation and transcript edits. It is not a universal requirement for every command that changes app data: import and transcription, remux, audio-sync, and model-download job starts do not take it. Sequence's access checks still apply.

Refine an existing variant with the same selection and ordering fields, omitting name:

sq app transcript apply-plan <variant-project-id> --plan ./edit-plan.json --confirm --json

The edit is applied atomically to the existing variant. includedSentenceIds is required for apply-plan; sentenceOrder is optional.

Edit transcript visibility

Enable or disable individual words or sentence groups by stable ID:

sq app transcript words disable <project-id> <word-id>... --confirm --json
sq app transcript words enable <project-id> <word-id>... --confirm --json
sq app transcript sentences disable <project-id> <sentence-group-id>... --confirm --json
sq app transcript sentences enable <project-id> <sentence-group-id>... --confirm --json

These commands change the edited transcript and require --confirm.

Analyse likely retakes and long pauses with the same cleanup policy used by the app:

sq app transcript cleanup <project-id> --json
sq app transcript cleanup <project-id> \
  --max-retake-gap 2 \
  --min-tokens 3 \
  --min-similarity 0.8 \
  --min-pause 0.35 \
  --json

The result includes stable sentence IDs, text, confidence, gap duration, and recommended exclusions. Cleanup is analysis-only; merge the recommendations you accept into a reviewed variant or transcript edit plan. Defaults are a 2-second maximum retake gap, 3 minimum tokens, 0.75 minimum similarity, and a 4-second minimum long pause. These analysis settings are separate from silence removal.

Inspect the edited timeline

Inspect the edited timeline used by Sequence playback and export:

sq app projection inspect <project-id> --json
sq app projection inspect <project-id> \
  --profanity-mode silence \
  --duration 600 \
  --offset 0 \
  --limit 100 \
  --json

Profanity modes are skip (the default), silence, beep, and textOnly. The result reports edited duration, projection identity, source ranges, audio-treatment counts, and paged per-segment explanations. The default page is offset 0, limit 100; limits range from 1 to 500. --duration supplies a fallback source duration when media duration is unavailable; it is not a target cut length. Use the projection to inspect the current cut before handing it back for review.

Inspect live readiness and project media

Read the app's live capability diagnostics, with or without the supporting evidence payload:

sq app diagnostics snapshot --json
sq app diagnostics snapshot --no-evidence --json

Probe a project's normalized media metadata through the same app resource:

sq app media probe <project-id> --json
sq app media probe <project-id> --allow-stale --json

Use --allow-stale only when cached metadata is acceptable.

For recording packages, inspect the inventory, stable streams, and health checks:

sq app media inspect-package <project-id> --json
sq app media list-streams <project-id> --json
sq app media validate-package <project-id> --json

For importing media and recording packages in the app, see Import your media.

Import into Sequence

Hand one or more files or folders to Sequence for sandbox-safe import:

sq app import /path/to/media.mov
sq app import /path/to/folder /path/to/another.mov --json
sq app import /path/to/interviews --transcribe

The --transcribe flag tells Sequence to transcribe supported media after import. Unlike standalone sq transcribe, this is an app-managed library workflow.

App-managed jobs

Start the same broker-backed jobs used by the app:

sq app jobs start-transcription <project-id> --json
sq app jobs start-transcription <project-id> --catalog <catalog-id> --force --json

sq app jobs start-remux <project-id> --json
sq app jobs start-remux <project-id> --catalog <catalog-id> --media /path/to/media.mov --json

sq app jobs start-audio-sync <project-id> --audio /path/to/audio.wav --json
sq app jobs start-audio-sync <project-id> --catalog <catalog-id> --force --json

sq app jobs start-model-download <pack-id> --json

Start a Final Cut Pro or DaVinci Resolve timeline export:

sq app jobs start-export <project-id> \
  --output /path/to/export.fcpxmld \
  --destination final-cut-pro \
  --confirm \
  --json

This timeline command supports final-cut-pro (the default) and resolve. Add --catalog <catalog-id> to specify the project's Catalog. Captions and keywords are included by default; use --no-captions or --no-keywords to omit them. It uses Regular Titles, source resolution and frame rate, MP3-to-M4A conversion, and no silent-channel removal. It does not inherit the inspector's saved export settings or create the transcript sidecars enabled in Settings. Export writes require --confirm. Poll the returned job ID to learn whether the export actually completed. If this project already has an active export, start-export returns that job rather than starting another one.

Export video, packages, frames, or an edited transcript

Use sq app run jobs.startDelivery for configurable NLE exports and the broader delivery destinations. These exports use a saved snapshot of the project's final edited timeline and transcript, unlike standalone transcription exports. Pass the exact editing variant or Multi-Cam programme UUID so the target is unambiguous:

sq app run jobs.startDelivery \
  --input-json '{"projectId":"<variant-id>","destination":"video","outputPath":"/path/to/cut.mp4"}' \
  --confirm --json

sq app run jobs.startDelivery \
  --input-json '{"projectId":"<variant-id>","destination":"srt","outputPath":"/path/to/cut.srt","splitMode":"sentences"}' \
  --confirm --json

sq app run jobs.startDelivery \
  --input-json '{"projectId":"<variant-id>","destination":"frame","outputPath":"/path/to/frame.png","timestampSeconds":10}' \
  --confirm --json

Replace <variant-id> inside the JSON with a real project UUID. JSON destination names are finalCutPro, resolve, package, video, frame, assets, txt, csv, sbv, srt, ass, and vtt; they are not the hyphenated options of start-export.

Use an absolute, new output path with no .. segments in an existing writable folder that Sequence can access. Existing outputs and companion files are not overwritten. Timeline deliveries use .fcpxmld, packages use .sqbundle, video uses .mp4 or .mov, and transcript/subtitle deliveries use the matching extension. Frame exports use .png, .jpg, or .jpeg; timestampSeconds is required, must be nonnegative and below the edited duration, and refers to the final edited delivery timeline, not source time. The assets destination links the variant into Assets and does not accept outputPath.

Video defaults include both audio and video at source resolution and frame rate with automatic codecs. For audio-only delivery, set includeVideo to false: use .m4a, or .wav with "audioCodec":"pcm". Transcript/subtitle splitMode defaults to sentences and also accepts words. Its cues follow the visible transcript on the final edited timeline, including insertion timing, not the source recording's original timestamps. A project without exportable transcript words cannot produce a transcript file. Packages include source media by default; set includeSourceMedia to false to omit it, and optionally supply encryptionCode to encrypt editing data. Add catalogId to verify the requested project belongs to the expected Catalog.

Keep Sequence open and unlocked while delivery runs. A successful start returns result.jobId, not a completed file. Poll with sq app jobs poll <job-id> --json; wait for completion before using the output, and inspect any failure or warning details. Unlike start-export, jobs.startDelivery rejects a second export while one is already active for that project.

Delivery settings and restrictions

Destination	Useful optional settings	Important limit
`finalCutPro`, `resolve`	`includeCaptions`, `includeKeywords`, `captionStyle`, `resolution`, `frameRate`, `removeSilentChannels`, `convertMP3ToM4A`, caption formatting	Source-linked FCPXML bundle, not a rendered movie or a guaranteed copy of all originals. Use `regularTitles` for Resolve.
`video`	`includeVideo`, `includeAudio`, `videoCodec`, `audioCodec`, `container`, `audioChannels`, resolution, frame rate, bitrates	Renders composition and audio, but does not burn captions or embed subtitle tracks. ProRes and video with PCM require MOV. H.264 cannot preserve HDR output.
`package`	`includeSourceMedia`, `encryptionCode`	Portable Sequence editing data. Encryption does not encrypt source media.
`frame`	Required `timestampSeconds`	Captures the composed edited timeline without relying on the open player. Requires visual content.
`assets`	Optional `catalogId`	Linked reusable variant, not an encoded file.
`txt`, `csv`, `sbv`, `srt`, `ass`, `vtt`	`splitMode`	Visible edited transcript only; request separately when a movie or NLE export also needs a sidecar.

For example, request a Final Cut timeline with Subtitle titles, or an audio-only WAV:

sq app run jobs.startDelivery \
  --input-json '{"projectId":"<variant-id>","destination":"finalCutPro","outputPath":"/path/to/cut.fcpxmld","captionStyle":"fcpSubtitles","includeKeywords":true}' \
  --confirm --json

sq app run jobs.startDelivery \
  --input-json '{"projectId":"<variant-id>","destination":"video","outputPath":"/path/to/cut.wav","includeVideo":false,"audioCodec":"pcm"}' \
  --confirm --json

Poll the first job to completion before starting another delivery for the same variant. Only destination-specific options are accepted; unsupported fields fail validation rather than being ignored. The MCP export settings reference lists the JSON setting names, accepted enum values, numeric ranges, and defaults used by this same delivery contract.

See the export format matrix, Final Cut Pro handoff, and Resolve import workflow before choosing a destination.

Poll and cancel jobs

Inspect or cancel background work:

sq app jobs poll
sq app jobs poll <job-id> --json
sq app jobs cancel <job-id> --confirm

Polling reports state; it does not wait until completion, and a successful poll command does not mean the job succeeded. Stop polling on a completed, failed, or cancelled job and handle that terminal outcome. Cancellation requests are cooperative for delivery jobs: an encode or source copy may finish its current operation before the job stops, and staged files are not published after cancellation.

Database maintenance

Database maintenance commands are deliberately explicit:

sq app diagnostics db --json
sq app db maintenance --confirm
sq app db compact --confirm
sq app db prune --keep-edits 100 --keep-history 100 --keep-stats 100 --dry-run

Run pruning with --dry-run first. Destructive commands require --confirm; scripts should not add that flag until they have validated the intended target and retention values.

Standalone transcription

Transcribe an audio or video file with a model already installed by Sequence. If you omit --model, sq selects the best available installed model:

sq models list
sq transcribe /path/to/interview.mov
sq transcribe /path/to/interview.mov --model parakeet-v3 --format words

The default output is transcript text on standard output. Use --format text, --format segments, or --format words to choose the detail level, and add --json for structured output. The older --text, --segments, and --words spellings are also accepted.

Save one or more transcript or subtitle formats beside the media:

sq transcribe /path/to/interview.mov --txt --srt
sq transcribe /path/to/interview.mov --vtt -o /path/to/interview.vtt
sq transcribe /path/to/interview.mov --csv --split words

Export formats are --txt, --csv, --sbv, --srt, --ass, and --vtt. Exports use sentence grouping by default; use --split words for word-level cues. Existing files are preserved unless you explicitly pass --force.

Recursively transcribe a directory by supplying at least one export format:

sq transcribe /path/to/interviews --txt --srt
sq transcribe /path/to/interviews --vtt -o /path/to/existing-output-directory

Batch mode skips hidden items, app/package directories, and unsupported files. When an output directory is supplied, it preserves the input directory structure.

Interactive terminals show progress automatically. Scripts can choose line-based progress with --progress, JSON Lines events on standard error with --progress-json, or no progress with --no-progress. Choose only one progress option. Use --verbose with any command when you need engine diagnostics; diagnostics may add output on standard output and standard error, so leave it off when parsing JSON.

Standalone CLI transcription runs in the foreground. It does not create a Sequence project, database row, or Action Center job, and it does not persist output unless you select an export format or redirect the command output.

JSON output and automation

Add --json to commands that support it when another program will consume the result. Successful result-producing commands return a versioned envelope:

{
  "schemaVersion": 1,
  "result": {}
}

Machine-readable errors are written to standard output and contain schemaVersion, operationId, numeric status, statusName, and error.message. Check the process exit status as well as the JSON: the numeric status is an action status, not necessarily the shell exit code. Treat additional result fields as compatible additions, and check schemaVersion before depending on a response shape. Help, version output, completions, and sq actions list are human-readable rather than result envelopes.

Use sq actions list to inspect the shared action catalog and its implementation status. sq run <action-id> --input-json '<json>' is a compatibility adapter for supported local actions. Use sq app run for app-owned actions, and the dedicated sq app import command for sandbox-safe file handoff. An action catalog entry is not a guarantee of headless availability: some actions still require visible UI or current macOS application state.

App access and security

The running app's same-user local broker takes precedence over direct database access. Project edits, variant creation, and app-managed job starts are broker-backed. Some library reads and database maintenance commands can use the authorized local database when the broker is unavailable and direct access is permitted; otherwise, sq attempts to launch Sequence in the background and reach its broker. MCP always requires the running app broker.

The app retains control of database keys, sandbox paths, licensing, and App Lock. Invalid or expired access fails closed, and a command reports when sign-in, activation, unlocking, or other interaction is required. The CLI never bypasses the app’s account or security settings.

Find projects and control a cut

Resolve a project by name, then use its stable ID to inspect variants and clips:

sq app projects find "Launch Talk" --json
sq app projects get <project-id> --json
sq app variants list <project-id> --json
sq app clips list <variant-id> --json
sq app transcript sentences dump <variant-id> --json
sq app open <variant-id> --json

Enable or disable whole clips, set the source-time trim range in seconds, or rename a detected speaker. Trim requires a nonnegative start and an end greater than the start; these are source bounds, not edited-timeline positions:

sq app clips disable <variant-id> <clip-id> --confirm --json
sq app clips enable <variant-id> <clip-id> --confirm --json
sq app trim get <variant-id> --json
sq app trim set <variant-id> --start 5 --end 120 --confirm --json
sq app trim clear <variant-id> --confirm --json
sq app speakers list <variant-id> --json
sq app speakers rename <variant-id> <speaker-id> --name "Alex" --confirm --json

Auto-clip a variant

Auto-clip identifies likely retakes, keeps the remaining sentences in source order, and creates clip rows for the retained ranges. It edits the supplied transcribed variant by default and requires --confirm to apply. Use --copy to create a new ordinary variant; copying a group-owned program this way is not supported. Auto-clip is a rough cut: it does not remove silence gaps or filler words.

Preview the proposed cut, then create a copy with a two-minute spoken-duration target:

sq app auto-clip <variant-id> --duration 120 --preview --json
sq app auto-clip <variant-id> --copy --duration 120 --name "Two-minute cut" --confirm --json

--120 is shorthand for --duration 120; duration must be a positive number of seconds. Omit it to retain all useful eligible content. The budget sums sentence durations, not the final exported runtime; whole sentences are retained, so the last sentence can exceed the target. Currently visible sentences are the working set; if all sentences are hidden, all become eligible.

Preview (--preview, also accepted as --dry-run) returns the plan without applying changes and does not need --confirm. The sentence sample is limited to the first 100 sentences; use transcript sentences list or dump for the transcript itself. The result's variantId identifies the cut to open or refine:

sq app open <returned-variant-id> --json
sq app auto-clip <variant-id> --copy --duration 120 \
  --export /path/to/cut.fcpxmld --destination final-cut-pro --confirm --json

--export starts a timeline export after applying the cut; it cannot be combined with preview. The destination defaults to final-cut-pro and also accepts resolve. The JSON result includes the export job under result.export; poll its job ID. If export startup fails, the cut may already have been applied, and the error identifies the affected variant.

Remove silence, filler, or profanity

Apply these independently from auto-clip to the variant you want to refine:

sq app silence remove <variant-id> --threshold 2 --confirm --json
sq app filler remove <variant-id> --confirm --json
sq app filler restore <variant-id> --confirm --json
sq app profanity remove <variant-id> --confirm --json

Silence removal persists cuts for transcript silence gaps; it is not a retake detector and does not alter locked clip ranges. --threshold is in seconds and accepts 0.5 through 20. Omit it to use the variant's effective silence threshold, falling back to 2 seconds when none is set. Filler removal hides eligible matching filler words; restoration shows words hidden as filler without undoing unrelated hide reasons. These filler actions also persist the variant's hide/show override. Profanity removal marks eligible words as profanity, so the project's profanity treatment determines playback and export.

These commands require --confirm. Use the returned result.projectId for subsequent commands: removal against an ordinary root project creates a child variant rather than editing the family container. Existing editing variants and group-owned programs are edited in place. Filler restoration requires an existing editing variant or program and does not create a copy.

Connect an AI assistant with MCP

See Connect an AI assistant with Sequence MCP for setup, available tools, edit sessions, and Agent Mode. MCP uses the running app and the same Automation access requirements described above.