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. It exposes supported Sequence Engine operations to Terminal, shell scripts, and other automation tools. Use it to transcribe or inspect media, import files, query projects and transcripts, monitor jobs, run maintenance, or produce machine-readable JSON.

The CLI and app share the same typed action implementations, but the Sequence app does not run its own work by spawning sq.

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.

Requirements

The supported release runs on Apple Silicon with macOS 15 or later. Commands under sq app require Sequence to be signed in and activated. If App Lock is enabled, open and unlock Sequence before running protected commands.

This guide covers Sequence CLI 1.1.2 with Sequence 1.4 or later. This includes markers, variants, edit plans, transcript visibility edits and cleanup analysis, projection inspection, live diagnostics, project media probes, and app-managed job starts. Check your installed version before using them:

sq --version

If the result is older than 1.1.2, update before continuing.

The CLI is versioned independently from the app. Matching version numbers are not required; compatibility is checked explicitly. Run sq app doctor when installing or troubleshooting it.

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.

CLI 1.1.2

CLI 1.1.2 adds project discovery, clip controls, trim controls, speaker naming, auto-clipping, and a local MCP server. App integration described here requires Sequence 1.4 or later; installing the CLI ahead of the app update does not enable those features in an older app.

Use Settings → Automation in Sequence to enable external automation and manage CLI and MCP setup. Use sq app doctor for app access and installation diagnostics.

Check the installation:

sq --version
sq app doctor

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 a full content hash, or use the faster path-based quick mode:

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

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:

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

CLI 1.1.1 can also page through stable sentence IDs, including hidden sentences when needed for an edit plan:

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 (CLI 1.1.1+)

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 (CLI 1.1.1+)

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.

The agent can discover the stable project and sentence IDs, generate the edit plan, preview it, and submit it itself. You do not need to inspect, save, or import a JSON file. JSON is the CLI's internal edit-plan format, not a manual handoff requirement.

To duplicate a project without sentence edits, use:

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

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 result contains the new variant's id. Sentence-group IDs remain stable for the plan, but copied words receive new IDs. Before making word-level edits, the agent should inspect the new variant 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 a project-changing CLI operation. It does not require you to open or manually review the JSON. Sequence must be signed in, activated, and unlocked before the protected operation can run.

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.

Edit transcript visibility (CLI 1.1.1+)

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.

Analyze likely retakes 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.

Inspect the edited timeline (CLI 1.1.1+)

Inspect the canonical Rust 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, silence, beep, and textOnly. The result reports edited duration, projection identity, source ranges, audio-treatment counts, and paged per-segment explanations. Use it to verify that a proposed cut matches playback and export before handing it back for review.

Inspect live readiness and project media (CLI 1.1.1+)

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.

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 (CLI 1.1.1+)

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.fcpxml \
  --destination final-cut-pro \
  --confirm \
  --json

Export destinations are final-cut-pro and resolve. Add --catalog <catalog-id> when project lookup needs a Catalog. Use --no-captions or --no-keywords to omit those elements. Export writes require --confirm.

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

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. Use --verbose with any command when you need engine diagnostics.

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 when another program will consume the result. Successful commands return a versioned envelope:

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

Machine-readable errors include a stable status name, operation ID, and error message. Treat additional result fields as compatible additions, and check schemaVersion before depending on a response shape.

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. CLI 1.1.2 exposes the shared broker-backed project actions documented above; catalog entries that still depend on visible UI or current macOS application state remain app-only and cannot run headlessly.

App access and security

When permitted, protected sq app commands use the authorised local database directly. Otherwise, sq can launch Sequence in the background and send the request through its same-user local 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 (CLI 1.1.2+)

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 trim range in seconds, or rename a detected speaker:

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 (CLI 1.1.2+)

Auto-clip identifies likely retakes, keeps the remaining sentences in source order, and creates clip rows for the retained ranges. It edits the supplied variant by default. Use --copy to create a new variant.

Preview the proposed cut, then create a two-minute copy:

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. Omit the duration to retain the full useful runtime. Preview returns the edit guidance and sentence information without applying changes. Use the returned variant ID with sq app open to review the result in Sequence.

Connect an AI assistant with MCP

CLI 1.1.2 includes Sequence's local MCP server. See Connect an AI assistant with Sequence MCP for setup, available tools, and Agent Mode. Sequence 1.4 or later must be open, signed in, activated, and unlocked, with Automation enabled.