Clivara

A modern terminal UI framework for JavaScript and TypeScript.

Beautiful human output. Structured machine output. Zero runtime dependencies.

npm install @ebdev/clivara

Why Clivara?

Building a polished CLI today usually means assembling Chalk + Ora + Inquirer + cli-table3 + boxen + log-update — each with its own API, CI behavior, and rendering model.

Clivara is a terminal presentation system: one theme, one capability layer, one render model, and three output modes (human / plain / JSON).

Quick start

import { createClivara } from '@ebdev/clivara';

const cli = createClivara();

cli.info('Starting build');
cli.success('Database connected');
cli.warning('Cache is disabled');

cli.table([
  { name: 'John', role: 'Admin', status: 'Active' },
  { name: 'Sarah', role: 'User', status: 'Active' },
]);

const spinner = cli.spinner('Running tests...');
spinner.start();
await runTests();
spinner.success('Tests passed');

cli.success('Build completed');
cli.destroy();

Output modes

createClivara({ output: 'human' }); // beautiful terminal (default on TTY)
createClivara({ output: 'plain' }); // no ANSI / animations
createClivara({ output: 'json' });  // machine-readable events

Same semantic events, different renderers:

| Call | Human | Plain | JSON | |---|---|---|---| | cli.success('Build completed') | ✓ Build completed | [SUCCESS] Build completed | {"level":"success","message":"Build completed"} |

Features

• Semantic logging (debug / info / success / warning / error)
• Themes (default, dark, light, Dracula, Nord, Monokai, Solarized, GitHub, Catppuccin, Tokyo Night)
• Tables, panels, trees
• Spinners, progress bars, multi-progress
• JSON / code / error + stack-trace formatting
• Interactive prompts (confirm, input, select, multiSelect, password)
• OSC 8 hyperlinks, gradients, ASCII banners
• Accessibility mode & CI awareness
• Responsive layouts (terminal width as viewport)
• Escape-injection sanitization
• 0 runtime dependencies

Themes

import { createClivara, createTheme } from '@ebdev/clivara';

const cli = createClivara({ theme: 'dracula' });

const custom = createTheme({
  primary: '#8b5cf6',
  success: '#22c55e',
  error: '#ef4444',
});
const cli2 = createClivara({ theme: custom });

Components

cli.table(data, { columns: { age: { align: 'right' } } });
cli.panel({ title: 'Build', content: 'Done' });
cli.tree([{ label: 'src/', children: [{ label: 'index.ts' }] }]);

const spinner = cli.spinner('Installing...');
spinner.start();
spinner.success('Installed');

const progress = cli.progress({ label: 'Download', total: 100 });
progress.start();
progress.update(50);
progress.complete();

cli.json({ ok: true });
cli.code('const x = 1;', { language: 'typescript' });
cli.error(new Error('Database connection failed'));

Accessibility & CI

createClivara({ accessibility: true });

Environment variables:

• NO_COLOR / FORCE_COLOR
• CLIVARA_ACCESSIBILITY=1
• CI and provider-specific vars (GitHub Actions, GitLab, Jenkins, CircleCI, Azure, Travis)

CI mode disables animations, avoids interactive prompts, and produces deterministic output.

Configuration

createClivara({
  output: 'human',
  theme: 'nord',
  accessibility: false,
  timestamps: false,
  logLevel: 'info',
  stream: customOutputStream, // injectable for tests / browser
});

Lower-level exports

import {
  createTheme,
  renderTable,
  formatError,
  detectTerminal,
  createStyler,
  gradient,
} from '@ebdev/clivara';

Security

User-controlled strings are sanitized against CSI / OSC / control-character injection. Clivara never executes shell commands or evaluates user strings.

Architecture

See docs/architecture.md and docs/competitive-analysis.md.

License

MIT