Invalid slug '${slug}': must be lowercase alphanumeric with

Error message

Invalid slug '${slug}': must be lowercase alphanumeric with hyphens only.

What it means

Slug format validation in `workflowInstallCommand`: the slug must match `/^[a-z0-9-]+$/` (lowercase letters, digits, hyphens only). Since the slug becomes the installed filename and is used in directory-membership checks, a strictly constrained format keeps it a safe path component.

Source

Thrown at packages/cli/src/commands/workflow.ts:5157

  force?: boolean
): Promise<void> {
  const entries = await fetchMarketplace();
  const entry = entries.find(e => e.slug === slug);

  if (!entry) {
    console.error(`Error: Workflow '${slug}' not found in marketplace.`);
    console.error("Run 'archon workflow search' to browse available workflows.");
    throw new Error(`Workflow '${slug}' not found`);
  }

  if (!entry.sourceUrl.startsWith('https://github.com/')) {
    throw new Error(
      `Untrusted source URL for '${slug}': ${entry.sourceUrl}\nOnly github.com sources are permitted.`
    );
  }

  if (!/^[a-z0-9-]+$/.test(slug)) {
    throw new Error(`Invalid slug '${slug}': must be lowercase alphanumeric with hyphens only.`);
  }

  const { findRepoRoot } = await import('@archon/git');
  const repoRoot = await findRepoRoot(cwd);
  if (!repoRoot) {
    throw new Error('Not in a git repository. Run archon workflow install from within a git repo.');
  }

  const { existsSync, mkdirSync, writeFileSync } = await import('node:fs');
  const archonDir = join(repoRoot, '.archon');

  if (isDirectoryUrl(entry.sourceUrl)) {
    await installDirectory(entry, slug, archonDir, force, existsSync, mkdirSync, writeFileSync);
  } else {
    await installSingleFile(entry, slug, archonDir, force, existsSync, mkdirSync, writeFileSync);
  }

  console.log(`Run with: archon workflow run ${slug} "<message>"`);

View on GitHub (pinned to 0773b97458)

Solutions

Re-run with only lowercase letters, digits, and hyphens
Trim surrounding whitespace: `archon workflow install "$(echo $slug | xargs)"`
Copy the slug exactly from `archon workflow search` output
Check shell quoting — quote the argument to avoid word-splitting

Example fix

// before
archon workflow install My_Workflow
// after
archon workflow install my-workflow

Defensive patterns

Strategy: validation

Validate before calling

const slug = raw.trim();
if (!/^[a-z0-9-]+$/.test(slug)) {
  throw new Error(`'${slug}' must be lowercase alphanumeric with hyphens`);
}

Type guard

function isValidSlug(s: string): boolean {
  return /^[a-z0-9-]+$/.test(s);
}

Try / catch

try {
  await workflowInstallCommand(slug);
} catch (e) {
  if (e instanceof Error && e.message.includes('Invalid slug')) {
    // normalize (lowercase, spaces→hyphens) and retry once
  } else throw e;
}

Prevention

Normalize user input: `.trim().toLowerCase().replace(/\s+/g, '-')` before passing slugs
Quote CLI arguments to avoid shell word-splitting
Validate slugs in scripts before invoking install
Copy exact slugs from search output

When it happens

Trigger: `archon workflow install '<slug>'` with an empty slug, uppercase letters, underscores, spaces, dots, slashes, or unicode characters. Only runs after the entry is found and its URL validated.

Common situations: Typing a display name like `PR Review` instead of a slug; copy-paste with trailing whitespace or newline; using `my_workflow` or `MyWorkflow`; shell quoting issues injecting spaces.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/7212b7d3f471dd3c. Report an issue: GitHub.