https://github.com/oharu121/cli-ascii-logo
Create beautiful ASCII art logos with gradient colors for your CLI applications.
https://github.com/oharu121/cli-ascii-logo
ascii ascii-art banner cli cli-tool figlet gradient logo terminal
Last synced: about 2 months ago
JSON representation
Create beautiful ASCII art logos with gradient colors for your CLI applications.
- Host: GitHub
- URL: https://github.com/oharu121/cli-ascii-logo
- Owner: oharu121
- License: mit
- Created: 2025-11-08T15:22:08.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-05-12T05:05:51.000Z (about 2 months ago)
- Last Synced: 2026-05-12T07:09:48.212Z (about 2 months ago)
- Topics: ascii, ascii-art, banner, cli, cli-tool, figlet, gradient, logo, terminal
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/cli-ascii-logo
- Size: 450 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# CLI ASCII Logo
[](https://badge.fury.io/js/cli-ascii-logo)
Create beautiful ASCII art logos with gradient colors for your CLI applications.
## Installation
```bash
pnpm add cli-ascii-logo
```
> **Note:** Version 2.1.0+ uses ES modules (ESM). If you need CommonJS support, use version 2.0.x or earlier.
## Usage
### CLI Usage
Use directly with npx (no installation required):
```bash
npx cli-ascii-logo "Hello World"
```
Or install globally:
```bash
pnpm add -g cli-ascii-logo
cli-ascii-logo "My App"
```
#### CLI Options
```bash
# Basic usage with default gradient (sunset)
cli-ascii-logo "Hello World"
# Use a specific gradient palette
cli-ascii-logo "Hello World" --palette cyberpunk
cli-ascii-logo "Hello World" -p ocean
# Use a random gradient
cli-ascii-logo "Hello World" --random
cli-ascii-logo "Hello World" -r
# List all available palettes
cli-ascii-logo --list
cli-ascii-logo -l
# Show help
cli-ascii-logo --help
cli-ascii-logo -h
```
#### CLI Examples
```bash
# Create a logo with the sunset gradient
npx cli-ascii-logo "MyApp"
# Create a logo with cyberpunk theme
npx cli-ascii-logo "CLI Tool" -p cyberpunk
# Generate with random colors
npx cli-ascii-logo "Surprise" --random
# See all available gradient options
npx cli-ascii-logo --list
```
### Programmatic Usage
## Quick Start
```typescript
import logo from "cli-ascii-logo";
// Simple usage with default gradient
console.log(logo.createLogo("Hello"));
// Use a specific gradient
console.log(logo.createLogo("My App", "rainbow"));
// Random gradient
console.log(logo.createRandomLogo("Surprise!"));
```
## API Reference
### Simple Methods
#### `createLogo(text: string, palette?: PaletteName): string`
Create a logo with a single call.
```typescript
logo.createLogo("MyApp", "sunset");
```
#### `createRandomLogo(text: string): string`
Create a logo with a random gradient palette.
```typescript
logo.createRandomLogo("Lucky");
```
### Builder Pattern (Advanced)
For more control, use the fluent builder API:
```typescript
logo.setText("MyApp").addFontStyle("ANSI Shadow", 120).build("ocean");
```
#### Methods
- **`setText(text: string): this`** - Set the text for the logo
- **`addFontStyle(font?: figlet.Fonts, width?: number): this`** - Apply ASCII art font
- **`build(palette?: PaletteName): string`** - Build and return the final logo
- **`addGradient(palette: PaletteName): string`** - Apply gradient and return (alternative to build)
- **`addRandomGradient(): string`** - Apply random gradient and return
## Available Gradients
### Custom Gradients
**Classic & Popular:**
- `sunset` - Warm orange to red (default)
- `ocean` - Deep blue to purple
- `fire` - Bold red to pink
- `forest` - Teal to green
- `gold` - Orange to yellow
- `copper` - Metallic bronze
**Cool Tones:**
- `blue` - Bright blue gradient
- `mint` - Cyan to blue
- `aqua` - Turquoise tones
- `ice` - Icy white-blue tones
**Warm Tones:**
- `lava` - Hot reds and oranges
- `volcano` - Dark red to gold
- `coral` - Soft pink gradient
- `cherry` - Pink-red
**Vibrant & Modern:**
- `cyberpunk` - Neon pink-cyan
- `neon` - Radioactive green
- `aurora` - Northern lights effect
- `lavender` - Soft purples
- `emerald` - Northern lights effect
**Special Effects:**
- `matrix` - Classic terminal green
- `nebula` - Purple to pink space
### Preset Gradients
From the `gradient-string` library: `cristal`, `teen`, `mind`, `morning`, `vice`, `passion`, `fruit`, `instagram`, `atlas`, `retro`, `summer`, `pastel`, `rainbow`
You can get the list programmatically:
```typescript
import { PALETTE_NAMES } from "cli-ascii-logo";
console.log(PALETTE_NAMES); // Array of all available palette names
```
## TypeScript Support
Full TypeScript support with exported types:
```typescript
import logo, {
PaletteName,
PALETTE_NAMES,
CUSTOM_GRADIENTS,
} from "cli-ascii-logo";
const palette: PaletteName = "sunset";
```
## Examples
### Basic Example
```typescript
import logo from "cli-ascii-logo";
console.log(logo.createLogo("Welcome", "rainbow"));
```
### Builder Pattern Example
```typescript
import logo from "cli-ascii-logo";
const myLogo = logo.setText("MyApp").addFontStyle("ANSI Shadow").build("ocean");
console.log(myLogo);
```
### Show All Palettes
```typescript
import logo, { PALETTE_NAMES } from "cli-ascii-logo";
PALETTE_NAMES.forEach((palette) => {
console.log(`\n--- ${palette} ---`);
console.log(logo.createLogo("Logo", palette));
});
```
### Rich Application Banner
Create a full banner with metadata (version, timestamp, etc.):
```typescript
import logo from "cli-ascii-logo";
import fs from "fs";
function printAppBanner() {
const pkg = JSON.parse(fs.readFileSync("./package.json", "utf-8"));
const logoText = logo.createLogo("wonderful\napp", "cyberpunk");
const banner = [
"=".repeat(80),
logoText,
`Version: ${pkg.version}`,
`Started: ${new Date().toLocaleString()}`,
"=".repeat(80),
].join("\n");
console.log(banner);
}
printAppBanner();
```
You can also apply gradients to the entire banner:
```typescript
function printColoredBanner() {
const pkg = JSON.parse(fs.readFileSync("./package.json", "utf-8"));
const logoText = logo.setText("wonderful\napp").addFontStyle().getText();
const bannerText = [
"=".repeat(80),
logoText,
`Version: ${pkg.version}`,
`Started: ${new Date().toLocaleString()}`,
"=".repeat(80),
].join("\n");
// Apply gradient to the entire banner
console.log(logo.setText(bannerText).addRandomGradient());
}
printColoredBanner();
```
## Advanced Features
### Animation Support
Display logos with animations:
```typescript
import logo from 'cli-ascii-logo';
// Display with fade-in animation
await logo.setText('MyApp').addFontStyle().display({
gradient: 'cyberpunk',
animation: 'fade-in',
duration: 2000,
clearBefore: true,
});
// Other animation types: 'slide-in', 'typing'
await logo.setText('Hello').addFontStyle().display({
animation: 'typing',
duration: 1500,
});
```
## Development
### Running Tests
```bash
# Run all tests
pnpm test
# Run tests in watch mode
pnpm run test:watch
# Run tests with UI
pnpm run test:ui
# Generate coverage report
pnpm run test:coverage
```
### Code Quality
```bash
# Lint code
pnpm run lint
# Auto-fix linting issues
pnpm run lint:fix
# Format code with Prettier
pnpm run format
# Check formatting
pnpm run format:check
```
### Building
```bash
# Build TypeScript to dist/
pnpm run build
```
## Dependencies
- [figlet](https://www.npmjs.com/package/figlet) - ASCII art text generation
- [gradient-string](https://www.npmjs.com/package/gradient-string) - Gradient color effects
## Dev Dependencies
- TypeScript 5.3+
- Vitest for testing
- ESLint 9 with flat config
- Prettier for code formatting
## Requirements
- Node.js >= 14.0.0
- ES Module support (ESM)
## License
MIT
## Contributing
Contributions welcome! Please ensure:
1. All tests pass (`pnpm test`)
2. Code is linted (`pnpm run lint`)
3. Code is formatted (`pnpm run format`)
4. Add tests for new features
Open an issue or PR on GitHub.