Snippet Expansion

Create and expand text snippets with dynamic placeholders

SuperCmd’s snippet system lets you create reusable text templates with dynamic placeholders for dates, clipboard content, and custom variables.

Overview

Snippets in SuperCmd provide:

• Quick text expansion - Type keyword, get full text
• Dynamic placeholders - Insert current date, time, clipboard, etc.
• Custom variables - Prompt for user input when expanding
• Import/Export - Share snippets or backup
• Search & organize - Pin favorites, search by name/content

Snippets are stored in ~/Library/Application Support/SuperCmd/snippets/snippets.json and sync automatically.

Quick Start

1. Open Snippet Manager

   Press SuperCmd hotkey, search for “Snippet Manager” or use Cmd+Shift+S.

2. Create Snippet

   Click Create New or press Cmd+N.

3. Set Name & Content

   • Name: Display name (e.g., “Email Signature”)
   • Keyword: Optional trigger (e.g., “sig”)
   • Content: Your text with optional placeholders
4. Use Snippet

   In Snippet Manager, select snippet and press Enter to copy, or Cmd+Enter to paste directly.

Snippet Manager UI

Implemented in src/renderer/src/SnippetManager.tsx:

Views

Search View

40/60 split layout:

• Left: Snippet list with search
• Right: Live preview with placeholder resolution

Actions: Copy, Edit, Delete, Duplicate, Pin

Create/Edit View

Form interface:

• Name field
• Keyword field (optional, for quick expansion)
• Content editor with placeholder insertion
• Preview panel showing resolved output

Toolbar: Insert placeholders, Save, Cancel

Snippet Organization

Snippets are sorted automatically (src/main/snippet-store.ts:101):

function getAllSnippets(): Snippet[] {
  return snippets.sort((a, b) => {
    // Pinned snippets first
    if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
    
    // Then by last updated (newest first)
    return b.updatedAt - a.updatedAt;
  });
}

Placeholders

Dynamic content insertion:

Built-in Placeholders

Placeholder	Output	Example
{clipboard}	Current clipboard text	”Hello, world!”
{date}	Current date (locale format)	“3/2/2026”
{time}	Current time (locale format)	“2:30 PM”
{date:YYYY-MM-DD}	Formatted date	”2026-03-02”
{time:HH:mm:ss}	Formatted time	”14:30:00”
{random:UUID}	Random UUID v4	”a3bb189e-8bf9-…”
{cursor-position}	Empty (marks cursor position)	-

Date/Time Formatting

Supported format tokens (src/main/snippet-store.ts:308):

function formatDate(date: Date, format: string): string {
  // YYYY - 4-digit year (2026)
  // MM   - 2-digit month (03)
  // DD   - 2-digit day (02)
  // HH   - 24-hour (14)
  // mm   - Minutes (30)
  // ss   - Seconds (45)
}

Examples:

• {date:YYYY-MM-DD} → “2026-03-02”
• {date:MM/DD/YYYY} → “03/02/2026”
• {time:HH:mm} → “14:30”
• {date:YYYY-MM-DD HH:mm:ss} → “2026-03-02 14:30:45”

Custom Variables (Arguments)

Prompt for user input when expanding:

Hello {argument name="Name"},

Your order #{argument:OrderID default="12345"} is ready.

Thank you!

When expanded, SuperCmd prompts:

• “Name” field (required)
• “OrderID” field (defaults to “12345”)

After filling in values, the snippet expands:

Hello John,

Your order #67890 is ready.

Thank you!

Argument Syntax (src/renderer/src/SnippetManager.tsx:35)

// Full syntax
{argument name="FieldName" default="DefaultValue"}

// Short syntax
{argument:FieldName}

// Examples:
{argument name="Email"}                    // Required field
{argument name="Country" default="USA"}    // Optional with default
{argument:FirstName}                       // Short form

Arguments are extracted and sorted for the prompt. The same argument name can appear multiple times in the snippet.

Snippet Keywords

Optional trigger phrases for quick expansion:

Setting Keywords

1. Edit snippet
2. Set Keyword field (e.g., “addr”)
3. Save snippet

Using Keywords

Currently, keywords are used for searching in Snippet Manager. Future versions will support inline expansion (type keyword → snippet expands).

Keyword Rules

Invalid characters are rejected (src/main/snippet-store.ts:27):

const INVALID_SNIPPET_KEYWORD_CHARS = /["'`]/;

if (INVALID_SNIPPET_KEYWORD_CHARS.test(keyword)) {
  throw new Error('Snippet keyword cannot include ", \', or ` characters.');
}

Keywords cannot contain quotes (”, ’, `) to prevent parsing issues.

Import & Export

Exporting Snippets

1. Open Snippet Manager

   Navigate to the Snippet Manager view.

2. Export Action

   Click the menu icon and select Export Snippets.

3. Save File

   Choose location and save as snippets.json.

Export Format (src/main/snippet-store.ts:352)

{
  "version": 1,
  "app": "SuperCmd",
  "type": "snippets",
  "exportedAt": "2026-03-02T14:30:00.000Z",
  "snippets": [
    {
      "name": "Email Signature",
      "content": "Best,\n{argument:Name}\n{argument:Title}",
      "keyword": "sig",
      "pinned": false
    }
  ]
}

Importing Snippets

1. Import Action

   Click menu icon > Import Snippets.

2. Select File

   Choose a snippets.json file (SuperCmd or Raycast format).

3. Review Results

   Toast shows: “Imported X snippets, skipped Y duplicates”.

Import Deduplication (src/main/snippet-store.ts:439)

for (const item of snippetsToImport) {
  // Skip if duplicate by name (case-insensitive)
  const exists = snippets.some((s) => 
    s.name.toLowerCase() === item.name.toLowerCase()
  );
  
  // Or skip if duplicate by keyword
  const exists = snippets.some((s) =>
    s.keyword && item.keyword && 
    s.keyword.toLowerCase() === item.keyword.toLowerCase()
  );
}

Duplicate snippets (by name or keyword) are skipped during import to prevent conflicts.

Raycast Compatibility

SuperCmd can import Raycast snippet exports (src/main/snippet-store.ts:423):

// Raycast uses "text" field, SuperCmd uses "content"
const content = item.content ?? item.text ?? '';

Both formats are supported automatically.

Snippet Actions

Available operations:

Action	Shortcut	Description
Copy to Clipboard	Enter	Resolve placeholders and copy
Paste Directly	Cmd+Enter	Copy and paste to frontmost app
Edit Snippet	Cmd+E	Open edit view
Duplicate	Cmd+D	Create copy of snippet
Pin/Unpin	Cmd+P	Pin to top of list
Delete	Cmd+Delete	Remove snippet
Clear All	Cmd+Shift+Delete	Delete all snippets

Placeholder Resolution

Processing pipeline (src/main/snippet-store.ts:261):

Resolution Order

1. Extract arguments - Find all {argument:...} placeholders
2. Prompt user - If arguments exist, show input form
3. Resolve placeholders:
   • Replace {argument:X} with user input
   • Replace {clipboard} with current clipboard
   • Replace {date} / {time} with current date/time
   • Replace {random:UUID} with generated UUID
4. Return final text

Example Resolution

Snippet:

Meeting Notes - {date:YYYY-MM-DD}

Attendees: {argument:Attendees}
Topic: {clipboard}

Action Items:
- 

With inputs:

• Attendees: “Alice, Bob”
• Clipboard: “Q1 Planning”
• Current date: 2026-03-02

Resolved:

Meeting Notes - 2026-03-02

Attendees: Alice, Bob
Topic: Q1 Planning

Action Items:
- 

Inline Argument Fields

When a snippet has 3 or fewer arguments, they appear inline in the snippet list (src/renderer/src/SnippetManager.tsx:33):

const MAX_INLINE_SNIPPET_ARGUMENTS = 3;

// If snippet has ≤3 arguments:
// - Show input fields directly in list
// - Press Enter to expand with filled values
// - No separate prompt dialog

Keep arguments to 3 or fewer for the best inline expansion experience.

Best Practices

Use Descriptive Names

Name snippets clearly: “Email Signature” not “sig1”

Set Keywords

Add keywords for frequently used snippets

Pin Favorites

Pin your most-used snippets to the top

Test Placeholders

Preview snippets before saving to verify placeholders

Common Use Cases

Email Templates

Hi {argument:Name},

Thank you for reaching out. I'll get back to you by {date:MM/DD/YYYY}.

Best,
{argument name="Your Name" default="John Doe"}

Code Snippets

// TODO({argument:Author}): {clipboard}
// Created: {date:YYYY-MM-DD}
// Priority: {argument name="Priority" default="Medium"}

Meeting Notes

# Meeting - {date:YYYY-MM-DD}

## Attendees
{argument:Attendees}

## Agenda
{clipboard}

## Notes


## Action Items
- [ ] 

Bug Report Template

**Bug ID:** {random:UUID}
**Date:** {date:YYYY-MM-DD HH:mm}
**Reporter:** {argument:Reporter}

**Description:**
{clipboard}

**Steps to Reproduce:**
1. 

**Expected:** 
**Actual:** 

Keyboard Shortcuts

Action	Shortcut
Open Snippet Manager	Cmd+Shift+S
Create New	Cmd+N
Search	Cmd+F
Edit Selected	Cmd+E
Duplicate	Cmd+D
Pin/Unpin	Cmd+P
Copy Snippet	Enter
Paste Snippet	Cmd+Enter
Delete	Cmd+Delete
Save (in edit view)	Cmd+S
Cancel (in edit view)	Escape

Troubleshooting

Placeholders not resolving

• Check placeholder syntax: {date} not {Date}
• Verify format string: {date:YYYY-MM-DD} not {date:yyyy-mm-dd}
• For arguments: use {argument:Name} not {Name}
• Preview snippet before saving to test

Import failed

• Verify JSON format is valid
• Check file has “snippets” array
• Ensure no duplicate names/keywords with existing snippets
• Try exporting a snippet first to see correct format

Snippet not appearing in list

• Check search query isn’t filtering it out
• Verify snippet was saved (check edit view)
• Look for the snippet in All filter (not type-specific)
• Restart Snippet Manager

Arguments not prompting

• Verify syntax: {argument name="Field"}
• Check no invalid characters in argument name
• Ensure snippet content includes the placeholder
• Try removing and re-adding the argument

Performance

Search Performance

Snippet search is fast even with hundreds of snippets (src/main/snippet-store.ts:111):

export function searchSnippets(query: string): Snippet[] {
  const lowerQuery = query.toLowerCase();
  return snippets.filter((s) => 
    s.name.toLowerCase().includes(lowerQuery) ||
    s.content.toLowerCase().includes(lowerQuery) ||
    (s.keyword && s.keyword.toLowerCase().includes(lowerQuery))
  );
}

Storage

• JSON format: Human-readable, easy to backup
• File size: ~1KB per snippet
• 1000 snippets: ~1MB file size
• Load time: Less than 50ms on app startup

Advanced Features

Nested Placeholders

Placeholders can reference each other:

Report for {date:YYYY-MM-DD}
Generated at {time:HH:mm:ss}
ID: {random:UUID}

Author: {argument:Author}
Data: {clipboard}

Multi-line Arguments

Arguments support multi-line input:

{argument name="Meeting Notes" default="No notes provided"}

When prompted, text area allows line breaks.

Preview with Highlighting

Preview panel highlights resolved placeholders (src/renderer/src/SnippetManager.tsx:64):

function renderSnippetPreviewWithHighlights(content, values) {
  // Argument values shown in emerald color
  // Other placeholders in muted color
  // Static text in default color
}

Use the preview panel to verify your snippet resolves correctly before copying.