Activate a lighting look by name or ID

Activate a look from a board (uses board's default fade time unless overridden).

Add a new cue to an existing cue list

Safely add fixtures to a look without affecting existing fixtures

Add a look as a button to a look board at a specific position.

Analyze the structure and timing of a cue list

Analyze specific fixtures to understand their lighting capabilities

Analyze a theatrical script to extract lighting-relevant information

Create multiple cue lists in a single operation.

Create multiple cues in a single operation. All cues are created in one GraphQL call for efficiency.

Create multiple fixture definitions in a single operation. Use this to efficiently add multiple fixture types (manufacturer/model combinations) to the system at once.

Create multiple fixture instances with best-effort approach. Each fixture is processed individually, allowing partial success if some fixtures fail. Returns detailed success/failure information for each fixture. Automatically assigns DMX channels if not specified. Validates channel availability before creation.

Create multiple buttons in a single operation.

Create multiple look boards in a single operation.

Create multiple looks in a single operation. Returns all created looks with their IDs.

Create multiple projects in a single operation.

Delete multiple cue lists in a single operation. Returns count of successfully deleted cue lists and any failed IDs.

Delete multiple cues in a single operation. Returns count of successfully deleted cues and any failed IDs.

Delete multiple fixture instances in a single operation. Returns count of successfully deleted fixtures and any failed IDs.

Delete multiple buttons in a single operation.

Delete multiple look boards in a single operation.

Delete multiple looks in a single operation. Returns count of successfully deleted looks and any failed IDs.

Delete multiple projects in a single operation. Returns count of successfully deleted projects and any failed IDs.

Update multiple cue lists in a single operation.

Update fade times and follow times for multiple cues in a single operation

Update multiple fixture instances in a single atomic operation. All updates succeed or fail together. Useful for batch renaming, repositioning, or re-tagging fixtures.

Update multiple buttons in a single operation.

Update multiple look boards in a single operation.

Update multiple looks in a single operation. Supports updating name, description, and fixture values.

Update multiple looks with partial fixture value merging support. Each look can independently specify name, description, fixtureValues, and mergeFixtures. Unlike bulk_update_looks, this preserves existing fixtures not mentioned in the update (when mergeFixtures=true). This is useful for batch operations like changing a channel value across many looks without affecting other fixtures.

Clear all operation history for a project.

WARNING: This is a destructive operation that cannot be undone. All undo/redo history will be permanently deleted.

Parameters:

• projectId: The project to clear history for

• confirmClear: Must be true to confirm the deletion

Returns:

• success: Whether the history was cleared

• message: Confirmation message

Copy fixture channel values from a source look to multiple target looks. This is an atomic operation that supports undo/redo. Useful for propagating lighting changes across multiple looks efficiently.

Create a sequence of lighting cues from existing looks

Create a new fixture instance in a project with manufacturer/model details

Create a new look board for organizing looks with custom layout.

Create a complete look board with buttons in a single operation. Allows defining an entire look board layout in one command.

Create a new lighting project

Delete a cue list and all its cues

Delete a fixture instance from a project (will remove it from all looks)

Delete a look board and all its buttons.

Delete a project and all its data

Ensure specific fixtures exist in a look with given values, adding only if missing

Export one data table (fixtures, looks, cue lists, look details, ...) as CSV or Excel.

• format "csv" (default): returns the CSV text inline so you can read it. Large exports are truncated (default 50000 characters), preferably at a line break, with truncated=true and a note. A cut is not guaranteed to fall between complete rows (a very long first line, or a quoted field containing line breaks, may be split); pass outputDirectory to also save the full file, or raise maxCharacters.

• format "xlsx": writes the Excel file to disk and returns its path, row count and size (no file content in the response).

Files are written to outputDirectory, else the LACYLIGHTS_EXPORT_DIR environment variable, else a private lacylights-exports folder in the system temp directory. Existing files are never overwritten; a numeric suffix is added instead. Use list_data_export_tables to see the tables and which need scopeId.

Export several project tables as one multi-sheet Excel (XLSX) workbook, one sheet per table.

Writes the file to disk and returns its path, total row count and size. Omit tables to export the backend's default set of project-level tables. FIXTURE_LIBRARY and scoped tables (LOOK_DETAILS, CUE_LIST_DETAILS, LOOK_BOARD_ENTRIES) cannot be included.

Export a LacyLights project as an ETC Eos ASCII (.asc) showfile.

Returns the file content as a string along with a suggested filename suffix and any export warnings. LacyLights-only concepts (Look Boards, per-channel fade behaviors, synthesized definitions) ride along as $$ LACYLIGHTS: comment lines at the end of file so a subsequent re-import preserves them. EOS itself ignores those comments.

Output is deterministic: the same project produces byte-identical output across runs.

Fade all lights to black (turn off)

Generate cue suggestions for an entire act based on script analysis

Generate a lighting look based on script context and design preferences

Get build information for the backend server.

Returns version, git commit hash, and build timestamp for the running lacylights-go server. This is useful for:

• Verifying the server version after updates

• Debugging version mismatches

• Confirming deployment success

Returns:

• version: Semantic version (e.g., "v0.8.10")

• gitCommit: Full git commit hash

• buildTime: UTC timestamp when the binary was built

Get the DMX channel usage map for a project

Get full details for a specific cue by ID.

Returns:

• Cue metadata (name, number, fade times, follow time, notes)

• Look information (id, name, description)

• Cue list information (id, name)

Use this when you need to inspect a single cue in detail.

Use cases:

• "Show me details for cue 5.5"

• "What look does this cue use?"

• "What are the fade times for this cue?"

Note: To look up a cue by number or name, use get_cue_list_details with filters and lookup tables instead.

Get cue list with its cues, optionally paginated.

Parameters:

• cueListId: Cue list to retrieve

• page: Page number (default: 1)

• perPage: Items per page (default: 50, max: 100)

• includeLookDetails: Include full look data for each cue (default: false)

• sortBy: Sort cues by cueNumber, name, or lookName

• filterBy: Optional filters (cueNumberRange, nameContains, etc.)

By default, each cue includes lookId and lookName but NOT full look fixture values. Set includeLookDetails=true only if you need full look data for every cue (this can be very large).

For large cue lists (50+ cues), use pagination to avoid context overflow.

Returns:

• Cue list metadata

• Paginated cues array

• Pagination info (total, page, perPage, hasMore)

• Statistics (averages, counts, ranges)

• Lookup tables for quick reference

Example workflow:

1. list_cue_lists(projectId) - Find available cue lists

2. get_cue_list_details(cueListId, page=1) - Get first page of cues

3. If pagination.hasMore, call with page=2, etc.

Get information about the currently playing cue list and navigation options

Get the currently active look if any

Get the current fade engine update rate in Hz.

The fade update rate controls how frequently the fade engine updates DMX channel values during look transitions. Higher rates provide smoother fades but use more CPU.

Returns:

• Current update rate in Hz (default: 60Hz)

• Whether the value is using the default

Typical values:

• 30Hz: Efficient, adequate for most theatrical lighting

• 60Hz: Default, smooth fades for professional use

• 120Hz: Very smooth, for critical applications

Get full details for a specific fixture.

Returns:

• All metadata (id, name, manufacturer, model, type, mode)

• DMX addressing (universe, startChannel, channelCount)

• Full channel definitions with types and ranges

• Tags

Use this tool when you need:

• Complete channel information for a fixture

• To understand fixture capabilities in detail

• Channel types and DMX value ranges

Use list_fixtures instead if you only need basic fixture information.

Get available lighting fixtures and their capabilities for a project or globally

Get full details of a group including its members, projects, and assigned devices. Requires the group ID.

Get full details for a specific look.

Parameters:

• lookId: Look to retrieve

• includeFixtureValues: Include all DMX channel values (default: true)

Set includeFixtureValues=false if you only need to know which fixtures are in the look, not their specific values. This is much faster for large looks.

Use get_look_fixtures instead if you only need fixture metadata.

Get a specific look board with all its buttons and layout information.

Get just the fixtures used in a look without their values.

Returns:

• Fixture IDs, names, and types

This is the fastest way to understand look composition without loading full DMX channel data.

Use cases:

• "Which fixtures does this look use?"

• "What type of fixtures are in this look?"

• Quick look composition analysis

Get current fixture values for a look (read-only)

Get the operation history for a project with pagination.

Returns a list of all recorded operations that can be navigated via undo/redo. Each operation includes:

• id: Unique operation ID

• description: Human-readable description

• operationType: CREATE, UPDATE, DELETE, or BULK

• entityType: Type of entity affected (Look, FixtureInstance, etc.)

• sequence: Position in the history

• createdAt: When the operation occurred

• isCurrent: Whether this is the current state

Use this to display an operation history timeline and allow jumping to specific points.

Get high-level project information including metadata and counts.

Returns:

• Project metadata (id, name, description, timestamps)

• Resource counts (fixtureCount, lookCount, cueListCount)

Does NOT include:

• Fixture details (use list_fixtures or get_fixture_inventory)

• Look details (use list_looks)

• Cue list details (use list_cue_lists or get_cue_list_details)

Use this tool first to understand project scope before drilling down into specific resources.

Get detailed information about a specific project including all fixtures, looks, and cue lists. This returns a lot of data and should only be used when you need comprehensive project information.

Get the current undo/redo status for a project.

Returns information about available undo/redo operations:

• canUndo: Whether undo is available

• canRedo: Whether redo is available

• currentSequence: Current position in the operation history

• totalOperations: Total number of operations in history

• undoDescription: Description of the operation that would be undone

• redoDescription: Description of the operation that would be redone

Use this to determine if undo/redo buttons should be enabled and to show tooltips.

Jump to a specific cue by number or name in the currently playing cue list

Import an ETC Eos ASCII (.asc) showfile into LacyLights.

Creates a new project (or appends into an existing one if targetProjectId is given) populated with the patch, cues, palettes, and groups from the Eos showfile. EOS-only concepts (effects, partitions, magic sheets, action triggers, curves, submasters) are skipped and surfaced as structured warnings. Palettes/presets are imported as standalone Looks in dedicated cue lists ("Color Palettes", "Beam Palettes", etc.).

Returns:

• projectId: the created or updated project

• counts of fixtures, looks, cue lists, cues, groups created

• warnings: structured list with code/severity/message/context entries

• synthesizedDefinitionIds: definitions auto-synthesized when no library match was found

Provide either newProjectName or targetProjectId, not both. If both are omitted, the project name comes from the showfile's $$Title.

Invite a user to join a group by their email address. Requires GROUP_ADMIN role in the target group. The invited user will receive a pending invitation they can accept or decline.

Jump to a specific operation in the history.

This allows navigating directly to any point in the operation history, effectively performing multiple undos or redos to reach the target state.

Parameters:

• projectId: The project containing the operation

• operationId: The ID of the operation to jump to

Returns:

• success: Whether the jump was successful

• message: Description of what happened

• operation: Details of the target operation

Use get_operation_history to get available operation IDs.

List all cue lists in a project with lightweight summaries.

Returns:

• Metadata (id, name, description)

• Cue count

• Total duration estimate

• Loop setting

Does NOT include:

• Individual cues (use get_cue_list_details)

• Look details (use get_look)

This is the most efficient way to browse available cue lists. Projects typically have < 10 cue lists, so no pagination needed.

Use cases:

• "What cue lists are available?"

• "Show me all cue lists in this project"

• Quick cue list overview

List the data tables that can be exported as CSV or Excel (XLSX), with their column headers and scope.

Each table has a scope that says which IDs export_data_table needs:

• none: global (FIXTURE_LIBRARY); projectId optional

• project: projectId required (FIXTURE_TYPES, FIXTURES, LOOKS, EFFECTS, CUE_LISTS)

• look: projectId + scopeId = look ID (LOOK_DETAILS)

• cueList: projectId + scopeId = cue list ID (CUE_LIST_DETAILS)

• lookBoard: projectId, optional scopeId = look board ID (LOOK_BOARD_ENTRIES)

Requires LacyLights backend v0.4.0 or newer.

List fixtures in a project with pagination and filtering.

Returns lightweight fixture information:

• Basic metadata (id, name, manufacturer, model, type)

• DMX addressing (universe, startChannel, channelCount)

• Tags

Does NOT include:

• Full channel definitions (use get_fixture for that)

• Look usage (use get_fixture_usage)

Pagination:

• Default: 50 items per page

• Max: 100 items per page

• Use pagination.hasMore to check if more results exist

Filtering:

• type: Filter by fixture type (LED_PAR, MOVING_HEAD, etc.)

• universe: Filter by DMX universe

• tags: Filter by tags (array)

• manufacturer: Filter by manufacturer name

• model: Filter by model name

Example workflow:

1. list_fixtures(projectId, page=1) - Get first page

2. If pagination.hasMore, call with page=2, etc.

List groups accessible to this device/user. Shows group names, member counts, and device counts. Groups determine which projects you can access.

List all look boards in a project.

Returns lightweight look board summaries with button counts.

List looks in a project with pagination and filtering.

Returns lightweight look summaries:

• Metadata (id, name, description)

• Fixture count

• Timestamps

Does NOT include:

• Fixture values (use get_look for that)

• Usage information (use get_look_usage)

This is the most efficient way to browse available looks.

Filtering:

• nameContains: Filter by look name (case-insensitive)

• usesFixture: Filter to looks using specific fixture ID

Sorting:

• name: Alphabetical by name

• createdAt: Oldest first (default)

• updatedAt: Recently modified first

List pending group invitations for the current user/device. Shows which groups you've been invited to, who invited you, and the offered role.

List all projects with optional detail level.

Parameters:

• includeDetails: When true, includes resource counts for each project. Default false.

Returns:

• Basic info (id, name, description) always

• Resource counts (fixtureCount, lookCount, cueListCount) when includeDetails=true

Use includeDetails=false for quick project listing. Use includeDetails=true when you need to understand project sizes.

Advance to the next cue in the currently playing cue list

Optimize the timing of cues in a cue list

Optimize an existing look for specific goals

Go back to the previous cue in the currently playing cue list

Get information about importing QLC+ (.qxw) files into LacyLights

Redo a previously undone operation in a project.

Re-applies an operation that was previously undone. Only available after an undo operation. If a new operation is performed after undo, the redo history is cleared.

Returns:

• success: Whether the redo was successful

• message: Description of what was redone

• operation: Details of the redone operation

• restoredEntityId: ID of the restored entity (if applicable)

Use get_undo_redo_status to check if redo is available.

Remove a cue from a cue list

Safely remove specific fixtures from a look

Remove a button from a look board.

Reorder multiple cues by assigning new cue numbers

Set the fade engine update rate in Hz.

The fade update rate controls how frequently the fade engine updates DMX channel values during look transitions.

Valid range: 10-120 Hz

Guidelines:

• 10-30Hz: Lower CPU usage, adequate for simple fades

• 30-60Hz: Good balance of smoothness and efficiency

• 60-120Hz: Maximum smoothness for professional applications

Note: Changes take effect immediately for new look transitions.

Start playing a cue list from the beginning or a specific cue

Stop the currently playing cue list

Suggest optimal channel assignments for multiple fixtures

Toggle the skip status of a cue. Skipped cues remain visible but are bypassed during playback.

Undo the last operation in a project.

Reverts the most recent change made to the project. Operations that can be undone include:

• Creating, updating, or deleting looks

• Creating, updating, or deleting fixture instances

• Creating, updating, or deleting cues

• Creating, updating, or deleting cue lists

Returns:

• success: Whether the undo was successful

• message: Description of what was undone

• operation: Details of the undone operation

• restoredEntityId: ID of the restored entity (if applicable)

Use get_undo_redo_status to check if undo is available.

Update properties of an existing cue

Update cue list name or description

Update an existing fixture instance with new properties

Update an existing look with new values

Update an existing look board's metadata and settings.

Update a look board button's properties (position, size, color, label).

Update positions of multiple buttons in a single operation (useful for drag-and-drop).

Safely update look metadata and optionally merge fixture values