Pucc

Installation

Get started with Pucc in seconds. Choose your preferred package manager:

Via pnpm/yarn/npm

pnpm add @mathiscode/pucc # or yarn add / npm install

Via Script Tag

<script src="https://unpkg.com/@mathiscode/pucc/dist/pucc.js"></script>

Usage

After including the library, commands are automatically available in the browser console:

$help()        // Lists all available commands
$about()       // Shows library information

Adding Custom Commands

Register a new command with ease:

Pucc.addCommand('new', (args) => {
  console.log('Creating:', args._[0]);
  console.log('Arguments:', args);
}, 'Create a new entity');

Now you can use it in the console or dropdown terminal:

$new('customer', 'name="John Smith"', 'balance=5400')
new customer name="John Smith" balance=5400

Terminal Types

Embedded Terminal

Embedded terminals are always visible on the page. Use the embedded attribute:

<pucc-terminal embedded="true"></pucc-terminal>

Dropdown Terminal

Dropdown terminals slide down from the top when activated via hotkey (default: Alt + S). Press Escape to close.

<pucc-terminal></pucc-terminal>

Configuration

Customize the terminal with attributes:

<pucc-terminal
  embedded="true"
  height="300px"
  theme="dark"
  prompt="# "
  hotkey="alt+s"
  initial-content="Welcome to my terminal!"
  pucc-options='{"enableGlobalRegistrations": false}'>
</pucc-terminal>

Attributes:

• embedded - Set to "true" for embedded mode
• height - Terminal height (e.g., "300px", "50vh")
• theme - Color theme ("dark" or "light")
• prompt - Custom prompt text (default: "$ ")
• hotkey - Keyboard shortcut for dropdown (e.g., "alt+s")
• initial-content - Custom initial content to display instead of the default welcome message (supports newlines)
• pucc-options - JSON string with Pucc constructor options (see "Passing Pucc Options to Terminal" card)

Command Execution

Browser Console

In the browser console, use the $ prefix and call it as a function:

$help()
$about()

Terminal Component

In embedded or dropdown terminals, type commands directly without the prefix:

help
about

Command Arguments

The command parser supports flexible argument formats:

Positional arguments:

$new customer
// args = { _: ['customer'] }

Key-value pairs:

$new name="John Smith" balance=5400
// args = { name: "John Smith", balance: 5400 }

Mixed (positional + key-value):

$new customer name="John Smith" balance=5400
// args = { _: ['customer'], name: "John Smith", balance: 5400 }

Type conversion:

• Numbers: balance=5400 → 5400 (number)
• Booleans: active=true → true (boolean)
• Strings: name="John" → "John" (string)

Module Import (ESM)

When using ESM, no global instance is created automatically. You have full control:

import { Pucc } from '@mathiscode/pucc';

// Option 1: Create a global instance (like IIFE build)
const shell = new Pucc();
shell.initialize();
// Now commands are available: $help(), $about()

// Option 2: Create a terminal-only instance
const shell = new Pucc({ enableGlobalRegistrations: false });
// Commands only available in terminal elements, not globally

Disabling Global Registrations

Limit commands to the terminal only (avoiding global namespace pollution):

import { Pucc } from '@mathiscode/pucc';

const shell = new Pucc({ enableGlobalRegistrations: false });

// Commands will only be available through the terminal
// They will NOT be accessible via window.$commandName
shell.addCommand('mycommand', (args) => {
  console.log('This command is only available in the terminal');
}, 'A terminal-only command');

Custom Command Prefix

Customize the command prefix (must be a valid JavaScript identifier):

import { Pucc } from '@mathiscode/pucc';

const shell = new Pucc({ commandPrefix: 'cmd' });

// Now commands can be called with the custom prefix
// cmdhelp() or cmdabout() in the console
// Or without prefix: help() or about()

shell.addCommand('greet', (args) => {
  console.log(`Hello, ${args._[0] || 'World'}!`);
}, 'Greet someone');

// Can be called as: cmdgreet('Alice') or greet('Alice')

Valid prefixes: $, _, cmd, myPrefix, prefix123, _prefix

The prefix must be a valid JavaScript identifier (starts with a letter, underscore, or dollar sign; can only contain letters, digits, underscores, and dollar signs).

Customizing Terminal Appearance with CSS

The terminal component supports CSS custom properties for advanced styling:

pucc-terminal {
  --shell-bg: #1a1a1a;
  --shell-fg: #e0e0e0;
  --shell-accent: #00aaff;
  --shell-border: rgba(255, 255, 255, 0.1);
  --shell-font-family: 'Courier New', monospace;
  --shell-font-size: 16px;
  --shell-padding: 20px;
  --shell-animation-duration: 0.3s;
  --shell-border-radius: 12px;
  --shell-shadow: 0 12px 48px rgba(0, 0, 0, 0.5);
  --shell-backdrop-blur: 15px;
}

Available CSS Variables:

• --shell-bg - Background color
• --shell-fg - Foreground/text color
• --shell-accent - Accent color (cursor, selection)
• --shell-border - Border color
• --shell-font-family - Font family
• --shell-font-size - Font size
• --shell-padding - Padding
• --shell-animation-duration - Animation duration
• --shell-border-radius - Border radius
• --shell-shadow - Box shadow
• --shell-backdrop-blur - Backdrop blur amount (dropdown terminals only)

Passing Pucc Options to Terminal

Configure Pucc options when using the pucc-terminal custom element:

Via attribute (simple options):

<pucc-terminal 
  embedded="true"
  pucc-options='{"enableGlobalRegistrations": false, "commandPrefix": "_"}'>
</pucc-terminal>

Via property (full functionality):

const terminal = document.querySelector('pucc-terminal');

terminal.puccOptions = {
  enableGlobalRegistrations: false,
  commandPrefix: 'cmd',
  customHelpHandler: (args, shell) => {
    console.log('Custom help!');
  },
  initialCommands: [
    {
      name: 'greet',
      description: 'Greet someone',
      handler: (args) => {
        console.log(`Hello, ${args._[0] || 'World'}!`);
      }
    }
  ]
};

Note: The pucc-options attribute only supports JSON-serializable options. For options that include functions, use the puccOptions property instead.

About the Author

Pucc is created and maintained by Jay Mathis, a developer passionate about building useful tools for the web.

Connect & Explore:

• GitHub Profile - Check out other projects and contributions
• Pucc Repository - Star, fork, or contribute to this project
• Website - Learn more about Jay and his work

Found Pucc useful? Consider giving it a star on GitHub! ⭐