Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mixn/carbon-now-cli

🎨 Beautiful images of your code — from right inside your terminal.
https://github.com/mixn/carbon-now-cli

cli cli-app cli-application cli-command cli-tool cli-utilities cli-utility command-line node nodejs

Last synced: about 5 hours ago
JSON representation

🎨 Beautiful images of your code — from right inside your terminal.

Awesome Lists containing this project

README

        

# [![Carbon CLI](static/banner.png)](https://github.com/mixn/carbon-now-cli)

> 🎨 Beautiful images of your code — from right inside your terminal.

[![Build Status](https://github.com/mixn/carbon-now-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/mixn/carbon-now-cli/actions) [![Code style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![Featured in awesome-nodejs](https://awesome.re/badge.svg)](https://github.com/sindresorhus/awesome-nodejs#command-line-apps) [![Twitter](https://img.shields.io/twitter/follow/mixn?style=social)](https://twitter.com/mixn) [![Stargazers](https://img.shields.io/github/stars/mixn/carbon-now-cli?label=Stars&style=social)](https://github.com/mixn/carbon-now-cli/stargazers/) [![Maintenance](https://img.shields.io/maintenance/yes/2030?label=Maintained&color=limegreen)](https://github.com/mixn/carbon-now-cli/graphs/commit-activity) [![Requirements](https://img.shields.io/node/v/carbon-now-cli?label=Node&color=limegreen)](https://img.shields.io/node/v/carbon-now-cli) [![MIT license](https://img.shields.io/github/license/mixn/carbon-now-cli?label=License&color=limegreen)](https://github.com/mixn/carbon-now-cli/blob/master/license)

## Table of Contents

- [Description](#description)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Presets](#presets)
- [License](#license)
- [Examples](#examples)

## Description

`carbon-now-cli` brings the power of [Carbon](https://carbon.now.sh/) directly to your terminal. ⚡️

Generate beautiful images of your code with a single command.

Want to customize *everything* before generating the image? Run it in `--interactive` mode. 💅

![Basic example](static/demo.gif)

## Features

- 🖼 Downloads the real, high-quality image (no DOM screenshots)
- ✨ Detects file type automatically
- 🗂 Supports all languages & [covers extra ground](https://github.com/mixn/carbon-now-cli/blob/master/src/helpers/cli/extensions-map.helper.ts)
- ⚡️ [Interactive mode](#fully-customized) via `--interactive`
- 🎒 [Presets](#presets) via `--preset` to save and re-use your favorite settings
- 🖱 [Selective processing](#selective) via `--start` and `--end`
- 📎 [Copies image to clipboard](#copying-to-clipboard) via `--to-clipboard` (cross-OS 😱)
- 📚 Accepts [file, `stdin`, or clipboard content](#input-sources) as input
- 🖋️ Supports [custom theme colors](#custom-theme-colors)
- 🥞 Supports concurrency for easier batch processing
- 👀 Saves to [given location](#full-example) or [opens in browser](#full-example) for manual finish
- 🐶 Displays image directly in supported terminals
- 🌈 Supports different export types (`png`, `svg`)
- 📏 Supports different resolutions (`1x`, `2x`, `4x`)
- ⏱ Reports each step and therefore shortens the wait
- ✅ Heavily tested
- ⛏ Actively maintained
- 🧺 …[and](https://github.com/mixn/carbon-now-cli/issues/50) [more](https://github.com/mixn/carbon-now-cli/issues/70)!

## Installation

### Bun

```
bun i -g carbon-now-cli
```

### pnpm

```
pnpm i -g carbon-now-cli
```

### npx

```
npx carbon-now-cli
```

### npm

```
npm i -g carbon-now-cli
```

### yarn

```
yarn global add carbon-now-cli
```

#### Requirements

[![Requirements](https://img.shields.io/node/v/carbon-now-cli?label=Node&color=limegreen)](https://img.shields.io/node/v/carbon-now-cli)

## Usage

```
Beautiful images of your code — from right inside your terminal.

Usage
$ carbon-now
$ pbpaste | carbon-now
$ carbon-now --from-clipboard

Options
--start, -s Starting line of input
--end, -e Ending line of input
--interactive, -i Interactive mode
--preset, -p Apply an existing preset
--save-to Image save location, default: cwd
--save-as Image name without extension, default: original-hash
--from-clipboard Read input from clipboard instead of file
--to-clipboard Copy image to clipboard instead of saving
--open-in-browser Open in browser instead of saving
--config Use a different, local config (read-only)
--settings Override specific settings for this run
--disable-headless Run Playwright in headful mode
--engine Use different rendering engine, default: `chromium`
Options: `chromium`, `firefox`, `webkit`
--skip-display Don’t display the image in the terminal

Examples
See: https://github.com/mixn/carbon-now-cli#examples
```

## Presets

### Creating a Preset

Running the `carbon-now` command generates a `~/.carbon-now.json` config file.

Presets are stored in this file and consist of [available settings](#settings). You can create presets either manually or automatically via the `--interactive` flag. When prompted, answer the following:

![Presets 1](static/presets-1.png)

For example, naming the preset `presentation` will add it to `~/.carbon-now.json` like this:

```ts
{
"latest-preset": {
// Equal to `presentation` below
},
"presentation": {
"theme": "base16-light",
"backgroundColor": "white",
"windowTheme": "none",
"windowControls": true,
"fontFamily": "Space Mono",
"fontSize": "18px",
"lineNumbers": false,
"firstLineNumber": 1,
"selectedLines": "*",
"dropShadow": false,
"dropShadowOffsetY": "20px",
"dropShadowBlurRadius": "68px",
"widthAdjustment": true,
"width": "20000px",
"lineHeight": "140%",
"paddingVertical": "35px",
"paddingHorizontal": "35px",
"squaredImage": false,
"watermark": false,
"exportSize": "2x",
"type": "png"
}
}
```

`latest-preset` will be overwritten after each run, while `presentation` remains until manually deleted.

### Using a saved preset

To use a saved preset, simply run:

```
carbon-now _unfold.js --preset
```

If the preset or `~/.carbon-now.json` does not exist, `carbon-now-cli` will fall back to the [default settings](https://github.com/mixn/carbon-now-cli/blob/master/src/config/cli/default-settings.config.ts) and be [smart about the rest](#re-using-settings).

**Result**:

![Presets 1](static/presets-2.png)

### Settings

```ts
interface CarbonCLIPresetInterface {
backgroundColor: string;
dropShadow: boolean;
dropShadowBlurRadius: string;
dropShadowOffsetY: string;
exportSize: '1x' | '2x' | '4x';
firstLineNumber: number;
fontFamily: CarbonFontFamilyType;
fontSize: string;
lineHeight: string;
lineNumbers: boolean;
paddingHorizontal: string;
paddingVertical: string;
selectedLines: string; // All: "*"; Lines 3-6: "3,4,5,6", etc.
squaredImage: boolean;
theme: CarbonThemeType;
type: 'png' | 'svg';
watermark: boolean;
widthAdjustment: boolean;
windowControls: boolean;
windowTheme: 'none' | 'sharp' | 'bw';
custom?: CarbonThemeHighlightsInterface;
width?: string;
// Below are detected automatically, and not persisted as keys
language?: string;
titleBar?: string;
}
```

Also see [`CarbonFontFamilyType`](https://github.com/mixn/carbon-now-cli/blob/master/src/types/carbon/global.d.ts), [`CarbonThemeType`](https://github.com/mixn/carbon-now-cli/blob/master/src/types/carbon/global.d.ts) & [`CarbonThemeHighlightsInterface`](https://github.com/mixn/carbon-now-cli/blob/master/src/types/carbon/global.d.ts)

### Re-using settings

#### *It just works.* ™

`carbon-now` automatically reuses settings from previous runs, so you don’t need to worry about manually reconfiguring them.

![Presets 3](static/presets-3.png)

### Custom theme colors

From `v2.0`, `carbon-now-cli` supports custom theme colors for detailed styling. Define a `custom` key inside a preset that complies to the following type:

```ts
interface CarbonThemeHighlightsInterface {
background?: string;
text?: string;
variable?: string;
variable2?: string;
variable3?: string;
attribute?: string;
definition?: string;
keyword?: string;
operator?: string;
property?: string;
number?: string;
string?: string;
comment?: string;
meta?: string;
tag?: string;
}
```

Example `~/.carbon-now.json` with custom theme colors:

```ts
{
"hacker": {
"backgroundColor": "rgba(0, 255, 0, 1)",
"windowTheme": "bw",
"windowControls": true,
"fontFamily": "Anonymous Pro",
"fontSize": "18px",
"lineNumbers": false,
"firstLineNumber": 1,
"dropShadow": false,
"selectedLines": "*",
"dropShadowOffsetY": "20px",
"dropShadowBlurRadius": "68px",
"widthAdjustment": true,
"lineHeight": "133%",
"paddingVertical": "30px",
"paddingHorizontal": "30px",
"squaredImage": false,
"watermark": false,
"exportSize": "2x",
"type": "png",
"custom": {
"background": "rgba(0, 0, 0, 1)",
"text": "rgba(0, 255, 0, 1)",
"variable": "rgba(0, 255, 0, 1)",
"variable2": "rgba(0, 255, 0, 1)",
"attribute": "rgba(0, 255, 0, 1)",
"definition": "rgba(0, 255, 0, 1)",
"keyword": "rgba(0, 255, 0, 1)",
"operator": "rgba(0, 255, 0, 1)",
"property": "rgba(0, 255, 0, 1)",
"number": "rgba(0, 255, 0, 1)",
"string": "rgba(0, 255, 0, 1)",
"comment": "rgba(0, 255, 0, 1)",
"meta": "rgba(0, 255, 0, 1)",
"tag": "rgba(0, 255, 0, 1)"
}
}
}
```

```
carbon-now _unfold.js --preset hacker
```

### Result:

![Presets 3](static/presets-4.png)

### Limitations

Please note that custom theme colors aren’t applied with `--open-in-browser` because they aren’t query string parameters but instead use `localStorage`, which is solely set inside the Playwright instance.

## Local configs

Use the `--config` flag for local configuration files. This is helpful for sharing presets across users in a project.

```
carbon-now _unfold.js --config local-config.json --preset dark
```

Local configs are **read-only** and differ from `~/.carbon-now.json` in that:

1. `local-config.json` won’t be created if it doesn’t exist.
2. `latest-preset` is not written to `local-config.json`.

## Examples

Assuming you have a file `_unfold.js` with this content:

```javascript
// Example from https://carbon.now.sh/
const unfold = (f, seed) => {
const go = (f, seed, acc) => {
const res = f(seed)
return res ? go(f, res[1], acc.concat([res[0]])) : acc
}
return go(f, seed, [])
};
```

### Basic

```
carbon-now _unfold.js
```

Uses [default settings](https://github.com/mixn/carbon-now-cli/blob/master/src/config/cli/default-settings.config.ts) and saves the image as `.png` in your `cwd`.

**Result**:

![Basic example](static/example-1.png)

### Fully customized

```
carbon-now _unfold.js --interactive
```

Launches interactive mode to customize every aspect, like theme, `font-family`, `padding`, etc.

**Input**:

![Example 2, Input](static/example-2-1.png)

**Result**:

![Example 2, Output](static/example-2-2.png)

### Selective

```
carbon-now _unfold.js --start 3 --end 6
```

Generates an image for lines `3` to `6`. Will throw an error if `--start` > `--end`.

**Result**:

![Example 3](static/example-3.png)

### Copying to clipboard

![Copying to Clipboard](static/clipboard-demo.gif)

Copies the image to clipboard instead of saving it. Requires `xclip` on Linux.

```
carbon-now _unfold.js --to-clipboard
```

#### Linux

[`xclip`](https://linux.die.net/man/1/xclip) is required. Install with

```
sudo apt-get install xclip
```

#### Windows & macOS

*It just works.* ™

### Input Sources

In addition to files, input from `stdin` or the clipboard is also supported.

#### `stdin`

```
pbpaste | carbon-now
echo '

Hi

' | carbon-now
```

#### Clipboard

```
carbon-now --from-clipboard
```

### Overrides

You can override settings on a per-run basis.

```
carbon-now _unfold.js --preset presentation --settings '{"theme": "nord", "titleBar": "custom-title.js"}'
```

**Result**:

![Example 4](static/example-4.png)

### Full Example

```
carbon-now _unfold.js --start 3 --end 6 --save-to ~/Desktop --save-as example-23 --interactive
```

Saves an image of lines `3`-`6` to `~/Desktop/example-23.png` with custom settings.

To preview in the browser instead of saving, do

```
carbon-now _unfold.js --start 3 --end 6 --interactive --open-in-browser
```

## License

MIT © [Miloš Sutanovac](https://twitter.com/mixn)