garrytan/gstack · error · Error

Usage: state save|load <name>

Error message

Usage: state save|load <name>

What it means

The `state` meta-command requires both an `action` and a `name`: `state save <name>` or `state load <name>` (lines 925-928). Missing either one throws this usage error before any filesystem or browser-state operation.

Source

Thrown at browse/src/meta-commands.ts:928

      }

      lines.push('────────────────────────────────');

      // Handle --clear flag
      if (args.includes('--clear')) {
        for (const file of files) {
          try { fs.unlinkSync(path.join(inboxDir, file)); } catch (err: any) { if (err?.code !== 'ENOENT') throw err; }
        }
        lines.push(`Cleared ${files.length} message${files.length === 1 ? '' : 's'}.`);
      }

      return lines.join('\n');
    }

    // ─── State ────────────────────────────────────────
    case 'state': {
      const [action, name] = args;
      if (!action || !name) throw new Error('Usage: state save|load <name>');

      // Sanitize name: alphanumeric + hyphens + underscores only
      if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
        throw new Error('State name must be alphanumeric (a-z, 0-9, _, -)');
      }

      const config = resolveConfig();
      const stateDir = path.join(config.stateDir, 'browse-states');
      mkdirSecure(stateDir);
      const statePath = path.join(stateDir, `${name}.json`);

      if (action === 'save') {
        const state = await bm.saveState();
        // V1: cookies + URLs only (not localStorage — breaks on load-before-navigate)
        const saveData = {
          version: 1,
          savedAt: new Date().toISOString(),
          cookies: state.cookies,

View on GitHub (pinned to 94993f7401)

Solutions

1. Use `browse state save <name>` to write cookies+pages to `<stateDir>/browse-states/<name>.json`.
2. Use `browse state load <name>` to restore them.
3. Pick a name matching `[a-zA-Z0-9_-]+` to also satisfy the regex guard (error 130).

Example fix

// before
browse state save
// after
browse state save login-session

if (args.length < 2 || !args[0] || !args[1]) {
  throw new Error('state requires an action (save|load) and a name');
}
if (!['save', 'load'].includes(args[0])) {
  throw new Error(`Unsupported state action: ${args[0]}`);
}

const isStateAction = (s: string): s is 'save' | 'load' =>
  s === 'save' || s === 'load';

When it happens

Trigger: `browse state` alone, `browse state save` (no name), or `browse state mysession` (no action).

Common situations: Forgetting the action verb, or the name; an agent truncating the command; shell splitting that merged tokens.

Related errors

• Usage: echo '[["goto","url"],["text"]]' | browse chain or
• Usage: browse diff <url1> <url2>
• Usage: frame <selector|@ref|--name name|--url pattern|main>
• Usage: frame --name <name>
• Usage: frame --url <pattern>

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/5dcd69503f947311. Report an issue: GitHub.