The Charm Blog

Crush + Docker MCP

Andrey Nering — Thu, 19 Mar 2026 00:00:00 +0000

Crush + Docker MCP

Get MCPs on-the-fly in Crush with Docker MCP.

By Andrey Nering on 19 March 2026

Two great flavors, all rolled into one

Say hello to the Docker MCP Catalog in Crush! We teamed up with Docker to natively integrate the Docker MCP Catalog into Crush and—if we do say so ourselves—it rocks.

During a conversation, Crush and Docker work together to pull in relevant MCPs on demand. Working with Postgres? Building a robot? Going deep on ARM? Crush and Docker will load in in the MCP you need, when you need it (and yes, Crush will still ask for permission).

Not only is this a great way to not think about config, it’s a great way to not think about MCP. Ironic, eh? Of course, if you do like thinking about MCPs you can ask Crush to add specific MCPs from the Docker MCP Catalog, too.

To get started, make sure Docker Desktop is running, then fire up Crush, press ctrl+p, choose “Enable Docker MCP Catalog”, and get to work. That’s it.

Set it and forget it

One of our favorite use cases is using the Hugging Face MCP to find an appropriate model for the current machine, pull it down, and run it.

A match made in heaven? Docker, Crush, and HuggingFace working together to run a local model.

Here are some of the other things we’re doing with Crush + Docker MCP:

Query your SQLite, MongoDB or Elasticsearch databases
Manage cloud stuff like AWS, Azure or Heroku
Send emails with Resend
Wrangle GitHub issues and pull requests
Interact with Unreal Engine
Search the Minecraft Wiki
And many others: see for yourself

We had a ton of fun building this with Docker and we hope you enjoy this new feature as much as we do.

Pro Tip

Some MCPs require secrets and configuration flags. If that happens, Crush will politely ask you to set them up, and it’s as simple as throwing a few commands on the ol’ CLI. For example, here’s how you would set up the Resend MCP:

docker mcp secret set resend.api_key={my_resend_key}
docker mcp config set resend.sender={my_email_address}
docker mcp config set resend.reply_to={my_email_address}

v2

Christian Rocha — Mon, 23 Feb 2026 00:00:00 +0000

v2

The next generations of Bubble Tea, Lip Gloss, and Bubbles are available now

By Christian Rocha on 23 February 2026

The next major versions of our terminal UI libraries—Bubble Tea, Lip Gloss, and Bubbles—are out of beta and ready to rock.

These releases bring highly optimized rendering, advanced compositing, higher-fidelity input handling, and a more declarative API for very predictable output.

The v2 branches have been powering Crush, our AI coding agent, in production from the very beginning. That is to say, everything we’re releasing today has run under real-world constraints, on our own products, for months.

For details as well as upgrade guides for humans and LLMs see:

But first, let’s talk about how we got here.

Why v2?

We started building terminal user interface tooling on the premise that the terminal is a better place to work (and play) than most people realize.

The foundation has always been there but what was missing was software for the next era and a lower barrier to entry for rich interaction. That’s where the innocently-named Bubble Tea (the interaction layer), Lip Gloss (the layout engine), and Bubbles (user interface primitives) began.

Today, the Bubble Tea ecosystem powers more than 25,000 open-source applications. Teams at NVIDIA, GitHub, Slack, Microsoft Azure and thousands of others build on top of them. And, throughout the history of the project, we’ve never pushed a breaking change.

So why a v2?

Things are changing. AI agents moved into the terminal, and suddenly the rest of the industry saw what many already knew: the terminal is the most powerful way to interface with the operating system. Coding tools followed. The terminal, which was previously somewhat of a niche preference, became a primary platform, and the weight it needed to carry changed. So we improved the parts that needed improving.

The heart of v2 is the Cursed Renderer. It’s modeled on the ncurses rendering algorithm and vastly improves what’s possible in our tooling. Rendering is faster and more efficient by orders of magnitude. For local applications this is very meaningful. For applications running over SSH, the changes are monetarily quantifiable.

v2 also reaches deeper into what emerging terminals can actually do. There’s richer keyboard support, inline images, synchronized rendering, clipboard transfer over SSH, and many more small, meticulous details. The terminal is quietly becoming far more capable than most developers realize, and v2 makes gracefully taking advantage of those capabilities very easy.

There’s a reason Bubble Tea supports inline mode as a first-class use case, a reason we chose a language that compiles to native machine code, and a reason we’re obsessed with performance in areas most frameworks don’t consider. The terminal is a powerful medium for both humans and machines, with real advantages—namely speed, composability, scriptability, and deep access to the OS—and it deserves production-grade software.

That’s v2.

Crush, Welcome Home

Christian Rocha — Wed, 30 Jul 2025 00:00:00 +0000

Crush, Welcome Home

We made the command line glamorous. Now we're making it intelligent.

By Christian Rocha on 30 July 2025

A few short months ago, Kujtim Hoxha set out to build something interesting that would get people’s attention. He built a terminal-based AI coding agent, and…it totally got our attention.

Kujtim reached for Go and the core of the Charm stack—Bubble Tea, Bubbles, Lip Gloss, and Glamour—tools we’ve been relentlessly building and refining for the past five years. What he created moved with remarkable speed and precision.

We were immediately floored upon seeing the project. Here was a developer who not only understood our tools deeply enough to build something exceptional with them, but who had the LLM expertise to help us realize our vision for AI-powered development tools. I caught the next flight to Prishtina, Kosovo to meet Kujtim in person, and the rest is history.

Kujtim’s project, now called Crush, has come home to Charm, where it was always meant to be. It will continue on with its original creator as well as the full support of the Charm team.

I remember my first Crush. No, it wasn’t a computer.

Why Now?

LLMs have most definitely crossed the threshold from impressive demos to genuinely useful tools. They can handle complex, multi-file reasoning and help developers work at speeds that were previously impossible. Take this website’s subtle background effect: a GLSL shader that generates layered Gaussian noise. What would have taken hours of digging through WebGL docs and trial-and-error debugging, I built with Crush in just a few minutes.

But powerful AI is only half the equation. To harness it effectively, you need the right tooling and the right user interface, and we believe that interface is the terminal. Developers already live there. It’s fast, scriptable, integrates seamlessly with existing workflows, and has all the wealth and power of the CLI at its fingertips. Crush can directly access the same tools you can (git, docker, npm, ghc, sed, nix and so on), and it can do so while running with extensive knowledge of the tools and extreme efficiency.

So why now? Because the timing is perfect. We’ve spent five years building the groundwork to make terminal experiences outstanding. Our tooling has matured into a powerful foundation for creating first-class terminal applications. Now we’re doubling down with Ultraviolet, our next-generation terminal UI toolkit that brings advanced compositing, lightning-fast rendering, and many other features we could previously only dream of.

Don’t forget to wear sunscreen.

We’re at a moment where everything is changing. The future of software development sits at the intersection of creative, new thinking around AI, user interfaces, collaboration, and culture. With Crush, we’re building exactly that.

Ready to Crush it?

With over 150,000 GitHub stars and upwards of 11,000 GitHub followers (more than many major tech companies) we’ve built a community that makes Crush possible: developers who understand that glamorous software is a force multiplier.

Come try Crush, let us know what you think, and help us build the future of both AI-powered development—and software itself.

Mods MCP Server Support

Bashbunni — Mon, 14 Jul 2025 00:00:00 +0000

Mods Now Supports MCP

By Bashbunni on 14 July 2025

Big news for AI enthusiasts out there: We now support MCP in Mods!

Mods

Built ItselfYep

AI on the command line.

MCP is a standardized way to add additional

All of this hard work was added Discord or via email at vt100@charm.sh.

So Hot Right Now: Lip Gloss v2 Beta 2

Andrey Nering — Mon, 30 Jun 2025 00:00:00 +0000 context and functionality to your LLMs, allowing you to connect them to various tools and data sources. For those who may be unfamiliar, let’s do a quick intro.

A bit about MCP servers

Model Context Protocol is an open source standard for connecting AI assistants to the systems where data lives. It allows developers to connect AI models to tools and data sources provided by MCP servers for extended functionality and context. It’s worth noting that the ability to tie in external sources as data to your LLMs isn’t what’s revolutionary here—it’s the fact that there is a standard protocol for it. That means reliability for app developers who want to support these enhancements in their AI applications.

Let’s jump into some examples of different MCP servers and their toolsets.

Say you’re using Supabase in your project. You connect your LLM to the Supabase MCP server to leverage its tools to interact with your Supabase project through your LLM. This allows you to do things like project management, database operations, project configuration, and more.

In some cases, MCP servers may be cloud-hosted by the organization or a local instance on your machine that you can run as a Docker container. Here’s an example using mods with GitHub’s MCP server to list issues related to a specific topic, in this case border colors, in the Lip Gloss repo.

mod chips > potato chips.

If all of this still feels like a lot, think of it this way: MCP servers allow you to work with external tools and data similar to an API, but since it’s integrated into your LLM, you can use natural language to direct these operations.

What’s changed in Mods

Getting your favorite servers up and running with Mods is simple. Just add MCP servers to your mods.yml file, just like Carlos did below. His example uses the GitHub, Puppeteer, Sequential Thinking, and Time MCP servers.

Heads up, you can open your config file with mods --settings. Use mods --help to learn more.

mcp-servers: github: command: docker env: - GITHUB_PERSONAL_ACCESS_TOKEN=xxxyyy args: - run - "-i" - "--rm" - "-e" - GITHUB_PERSONAL_ACCESS_TOKEN - "ghcr.io/github/github-mcp-server" puppeteer: command: docker args: - run - "-i" - "--rm" - "--init" - "-e" - DOCKER_CONTAINER=true - mcp/puppeteer sequentialthinking: command: docker args: - run - --rm - -i - mcp/sequentialthinking time: command: docker args: - run - -i - --rm - mcp/time - --local-timezone=America/Sao_Paulo in the latest release.Whatcha think?
Have some feedback on this post? We’d love to hear it. Let us know on
So Hot Right Now: Lip Gloss v2 Beta 2
By Andrey Nering on 30 June 2025
This release builds on top of the last Beta 1 release. It includes a new API for compositing layers and views, table enhancements, and a bunch of bug fixes. Let’s get into it!
Compositing
Compositing looks so nice, doesn't it?
The big news in this release is compositing. Here’s what it looks like:
box := lipgloss.NewStyle().
    Width(10).
    Height(5).
    Border(lipgloss.NormalBorder())

// Make some layers.
a := lipgloss.NewLayer(box.Render("Who wants marmalade?"))
b := lipgloss.NewLayer(box.Render("I do!"))

// Put layers in a canvas.
canvas := lipgloss.NewCanvas(
    a.X(5).Y(10).Z(1),
    b.X(3).Y(7)
)

// Render it all out.
lipgloss.Println(canvas.Render())
Also note that layers can also be nested (see Layer.AddLayers).
Otherwise, that’s all there is to it!
For more info see Layer, Canvas, and the compositing example.
Big shout out to @aymanbagabas for his work
on this feature!
Table Enhancements
Tables are one of the most beloved Charm components, and we’ve been working to
make them as polished as possible. In this release I
(@andreynering) fixed several bugs
and did many other rendering enhancements. You can check most of the fixes in
this pull request.
We’re also refactoring the Bubbles’ table component to use the Lip Gloss’ table package, and making their APIs similar, as before they were relatively different. This means that if you use Tables via Bubbles in your Bubble Tea app, you’ll be able to reap the benefits soon too!
Whatcha think?
Have some feedback on this post? We’d love to hear. Let us know in
Discord or via email at
vt100@charm.sh.



Markdown Tables Have Never Looked Better
Bashbunni — Mon, 21 Apr 2025 00:00:00 +0000
Markdown Tables Have Never Looked Better
By Bashbunni on 21 April 2025
Tables in Glamour, our markdown renderer, got a big
makeover in v0.10.0 last week with UX improvements for screen
reader compatibility and general legibility. Here’s a little sneak peek of the
process.
How it Started
Okay, so here’s what tables with a bunch of links used to look like:
While working with the GitHub CLI team, we received feedback that links
were interrupting the flow of text, which really hurt accessibility and just
made tables really hard to read. They were also spanning multiple lines when
they would wrap, making them impossible to click. We realized we had a nice
opportunity to improve table rendering in the terminal in a big way.
How it’s Going
Rethinking how we were rendering links was the perfect opportunity to fix
broken links, text legibility, AND improve accessibility in one fell
swoop. After much consideration, we removed the URL from the table and instead
opted to show it below instead.
A big thank you to Andy, William and Kynan on the GitHub CLI team for
working with us in this redesign, and a big shout out to
Andrey Nering here on the Charm team who
absolutely crushed this release, from design to implementation. 💫
A GitHub Bonus
As a little bonus we also improved rendering for GitHub URLs, inspired by our
friends at GitHub. Check it out:
Hungry for more?
Want all the details on this release? Then you’ll want to read the full release notes on Glamour v0.10.0.
Whatcha think?
Have some feedback on this post? We’d love to hear. Let us know in
Discord or via email at
vt100@charm.sh.


A Brief History of Terminal Emulators
Ayman Bagabas — Tue, 11 Mar 2025 00:00:00 +0000
A Brief History of Terminal Emulators
By Ayman Bagabas on 11 March 2025
If you’re reading this, you’ve probably used a terminal emulator before. But
have you ever wondered how this modern—yet archaic—tool came to be?
In this post, we’ll explore the history of terminal emulators, from the
earliest typewriters and teleprinters to modern video terminals and the
terminal emulators of today. Let’s go!
Early Terminals and Typewriters
This Olivetti Lettera 22 typewriter is not a terminal, but terminals were totally based on typewriters. The new line and carriage return lever is on the left. On the right, the paper roller and the paper release lever. The cursor is the horizontal line on the paper where the next character will be typed.
No, people did not use typewriters to interact with computers, but the first
terminals evolved from typewriters. In case you are not familiar with
typewriters (wink wink, kids) typewriters started as mechanical devices
introduces in the 1840s to type text on paper. They feature a keyboard for
input and paper for output. A cursor indicated the current text position,
moving as the user typed. Special components such as levers, handles, and keys
enabled cursor movement, space insertion, and paper scrolling.
Now with typewriters, communication was simple: type a letter, and it appears
on the paper, and later on, you would mail it to someone. After the invention
of telegraphs and telephones, people wanted to send messages faster. This need
prompted the development of teleprinters, which could send and receive messages
over telegraph and phone lines.
Teletype Writers (TTYs)
The infamous low-cost all mechanical Model 33.
The Teletype Corporation trademarked the term “teletype” for its teleprinters
back in 1928. The name then became a synonym for all teleprinters especially in
the field of computers. The basic idea behind a teleprinter is simple, you
have two machines linked together by a wire or wirelessly. When you type a
letter on one machine, the other machine prints the same letter. This way, you
can send messages back and forth between the two machines. It’s like a
typewriter, but instead of typing on paper, you’re typing on a machine that
sends the message to another machine that prints it out to paper ¹.
The Teletype Model 33, shown above, was one of the most popular teleprinters in
the 1960s and 1970s. It was a low-cost all-mechanical teleprinter that could
send and receive messages over phone lines. What made it special was that it
could understand the ASCII standard which made it compatible with computers.
Later on with the advent of interactive computing, people started connecting
ASCII aware teleprinters to computers. This way, they could type commands on
the teleprinter, and the computer would execute them and send the results back
to the teleprinter. This setup allowed users to interact with computers in real
time, enabling a wide range of applications and use cases.
Slowly, in the 1960s and 1970s, companies such as IBM, HP, and DEC started
experimenting with computer terminals. These terminals replaced the teleprinters
which significantly reduced paper waste and improved user experience. However,
many computer operators stuck with the teleprinters because they were more
affordable and familiar.
Fun Fact: The term “TTY” (short for TeleTYpe) is still used today to refer
to text-based terminals and terminal emulators in Unix-like operating systems.
Computer Terminals
VT100 was one of the first terminals to support ANSI escape codes and colors.
The introduction of computer terminals marked a significant advancement in
terminal and computing technology. A terminal is a device that allows users to
interact with computers, execute commands, and manage files and systems. Video
terminals come with a keyboard that is connected to electromechanical CRT
displays. They replaced teleprinters connected to computers. Above is the
legendary DEC VT100 released in 1978 was one of the first video terminals that
supported ANSI escape codes and colors.
Unlike mechanical teleprinters and typewriters, computer terminals needed a way
to communicate with computers in a backward-compatible fashion. Think about it,
how would you tell the computer to move the paper up? Or instruct it to move
the cursor to the next line? In a non-mechanical world, they needed a way to
send these commands from and to the computer. This is where ANSI standards and
escape codes came into play.
Because of the popularity, features, and adoption of the DEC VT100, and because
it adhered to many ANSI standards, it influenced many other terminals to adopt
the ANSI standards as well which later became the de facto standard for
terminal emulators.
Did you know? These standards are still relevant today, and they are the
reason why you can change the color of your terminal text, move the cursor
around, and clear the screen. The American Nation Standards Institute (ANSI),
formerly known as the American Standards Association (ASA), standardized the
ASCII character encoding which carried over to other standards such as X3.64,
ECMA-48, and ISO/IEC 6429 that are used today in terminal emulators.
Terminal Emulators
As the name suggests, a terminal emulator is a software application that
“emulates” the functionality of a traditional computer terminal. Instead of
being a physical device connected to an external computer, a terminal emulator
is a software program that runs on a computer and provides a text-based
interface for interacting with the operating system.
Back in the day, computers were big, heavy, and expensive. They were usually
located in separate rooms, and users would interact with them using terminals
in a time-sharing fashion. With the advancement of personal computers and
operating systems, terminal emulators became popular as a way to interact with
the computer directly. It also provides users with a backward-compatible way to
run legacy applications and systems that were designed for the old days of
computers and traditional terminals.
The Amazing XTerm
XTerm was one of the early modern terminal emulators.
Created in 1984, XTerm is a terminal emulator for the X Window System. It
started based on the DEC VT102 terminal specs and later incorporated features
from other DEC terminals like the VT220, VT320, VT420, VT520, and Tektronix 4014. Over time, XTerm introduced its own proprietary escape sequences, enabling
new features and enhanced functionality while adhering to most
ANSI, ECMA, and ISO standards.
As XTerm evolved and became more popular with new features, it influenced other
terminal emulators to adopt similar features and standards. This made XTerm a
kind of a standard when it comes to developing new terminal emulators. The
popular Xterm.js, no pun intended, gets its name from
the original XTerm but has no affiliation with it.
Today, XTerm is still being updated and improved, making it one of the oldest
still maintained terminal emulator out there.
Modern Terminal Emulators
Yes, this is Rio Terminal.
Nowadays, terminal emulators have evolved significantly from their early
predecessors. Modern terminal emulators offer a wide range of features and
customization options, allowing users to tailor their terminal experience to
their needs and preferences. These tools provide a powerful interface for
interacting with operating systems, executing commands, and managing files and
systems efficiently.
Some notable terminal emulators used today include:
Alacritty
Apple Terminal
Ghostty
GNOME Terminal and other VTE based terminals
iTerm2
KiTTY
Konsole
Linux console
PuTTY
Rio Terminal
Rxvt
St (a.k.a. simple terminal)
Windows Terminal
Xterm.js (not affiliated with XTerm)
XTerm
’Till Next Time
Terminal emulators have come a long way since the early days of typewriters and
teleprinters. It’s fascinating to see how these tools have evolved over time,
adapting to new technologies and user needs. Stay tuned for more posts on
terminal emulators and escape sequences, where we’ll explore these topics in
greater detail.
Whatcha think?
Have some feedback on this post? We’d love to hear. Let us know in
Discord or via email at
vt100@charm.sh.
https://www.howtogeek.com/727213/what-are-teletypes-and-why-were-they-used-with-computers/ ↩︎


Leveling up Cryptography at Charm
Bashbunni — Thu, 11 Jul 2024 00:00:00 +0000
Leveling up Cryptography at Charm
By Bashbunni on 11 July 2024
Filippo trapped at Charm HQ
Supporting open source
If you’re familiar with Charm tools, you’ll know we love SSH.
Filippo casually maintains the cryptography packages that ship as
part of the Go standard library. This includes our beloved
golang.org/x/crypto/ssh, crypto/ed25519, and age packages.
Insanely impressive!
We’re thrilled to support his work on these open source packages that are so
critical for us.
Becoming a full-time open source maintainer…at scale
Instant noodles not required
Filippo is revolutionizing what it means to be an open source maintainer by
finding creative ways to make this line of work sustainable…and it’s working!
So well, in fact, that he’s expanding his operation into
a firm of full-time independent open source maintainers, known collectively as
Geomys. First on the roster are Nicola Murino,
who is the dedicated maintainer for golang.org/x/crypto/ssh, and
Dominik Honnef who maintains staticcheck and
gotraceui.
We’re proud and honored to support him and Geomys on their journey while they
support our team with their vast knowledge of cryptography and Go expertise. In
working with Geomys, we are maximizing our potential by connecting with the
maintainers of tools we depend on and love.
You can hear the entire story in his own words over on his blog.
Encrypted files with SSH keys?!
Pronounced with a hard G, like chicken karaage.
$ age -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age
$ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg
Behind the scenes, we’ve been honing Charm’s encryption tooling. Naturally,
this brought us to age, a file encryption tool, format, and Go
library built by @FiloSottile and friends.
SSH
We love finding creative ways to use the SSH protocol (see wish,
melt, wishlist). This is why age really stands out to us.
It supports encrypting files to SSH public keys (both ssh-rsa and
ssh-ed25519) which can then be decrypted with their corresponding private
keys. Hello?! That is so cool. We’re all totally geeking out over here.
This also means it’s suddenly convenient to encrypt documents for non-GPG users,
for example, after yoinking SSH public keys from a GitHub profile like so.
$ curl https://github.com/benjojo.keys | age -R - example.jpg > example.jpg.age
File encryption beyond GPG
When people think file encryption, GnuPG is typically what comes to mind. Given
this, let’s compare GnuPG and age. There was a discussion about it on
GitHub, but I’ll give you the summary.
Age makes it easy to encrypt using common best practices as these are defined by
the age developers as defaults. GnuPG requires the user to be more aware of
these best practices to get the right results with the tool. If you don’t know
much about which encryption protocols to use depending on the context, no worries,
age gives you training wheels so you can’t fall off the cryptographic bike.
We’ll leave it to you to decide for yourself if you’re ready to be an age superfan.
Additional reading (for the nerds)
Filippo’s Blog
Filippo’s GitHub
Whatcha think?
Have some feedback on this post? We’d love to hear. Let us know in
Discord or via email at
vt100@charm.sh.


A coffee shop for your terminal
Bashbunni — Thu, 06 Jun 2024 00:00:00 +0000
A coffee shop for your terminal
By Bashbunni on 6 June 2024
The terminal got a whole ’lotta love recently when a handful of developers, with a combined following of over 1 million, dropped a new coffee line available for purchase exclusively from the terminal using the Charm stack. That’s right, they built an e-commerce app over SSH to allow developers to refill their coffee IVs right from the comfort of the command line. Talk about a modern day luxury.
ThePrimeagen and TJ DeVries building with Charm on a live stream to thousands of viewers, no pressure
The project itself is terminal.shop, which leverages Charm tooling at every level to not only sell coffee, but to absolutely demolish their inventory. The coffee company managed to sell out within days of becoming available.
A terminal coffee shop with no coffee, restocking soon!
The product first launched at one of the biggest tech conferences in the world, React Miami, which brought a lot of web developers over to the command line. Their reach has been impactful, boasting about 5 million impressions on Twitter surrounding terminal.shop and Charm as a result.
A tweet about the team taking over React Miami
Behind the scenes, the team worked to build a TUI for their users with Bubble Tea while Lip Gloss swooped in to provide some lovely styles that came to resemble exactly what they had planned in their Figma designs. Wish allowed them to ship this app to users through a secure connection without the hassle of managing SSL certificates.
Adamdotdev falling in love with Charm
It was a pleasure (and a curse) to see them build the whole thing live on stream. Thousands of developers were tuned in to watch Prime and TJ put together this command line app, no pressure or anything. The stream was spent hacking away with charm libraries guiding them towards a beautiful end result.
First day of them building in public with Charm, crushing it!
Second day of them building in public with Charm, highly caffeinated.
We spoke to the team after and found that the toughest part of working with the Charm tools was becoming familiar with the functional design of Bubble Tea. Given the scale of this project, we were pleasantly surprised to hear that was their biggest obstacle. They seem to be happy continuing to hack away on more command line projects. We’ve converted even the web developers to write some Go, just don’t ask about their backend… 💀
Thank you to the incredible terminal.shop team. Please continue to keep inspiring us all!
@adamdotdev
@thdxr
@ThePrimeagen
@teej_dv
@iamdavidhill
Adam working through the learning curve
Try it for yourself:
DIY SSH server (Wish)
Styling and layouts (Lip Gloss)
Interactive TUIs (Bubble Tea)
Quick forms (Huh)
Reusable components for Bubble Tea (Bubbles)
Whatcha think?
Have some feedback on this post? We’d love to hear. Let us know in
Discord or via email at
vt100@charm.sh.


Identifying Trends in Your Repos’ Issues…with AI!
Bashbunni — Thu, 02 May 2024 00:00:00 +0000
Identifying Trends in Your Repos’ Issues…with AI!
By Bashbunni on 2 May 2024
It’s a lot of work trying to keep up with what’s happening in your code repos,
let alone deciding what to focus on, but thankfully here’s where AI can come in
handy. I don’t think AI can actually do your job for you, but it provides
excellent base content to work from, hence why AI is the perfect partner for
this type of problem.
So you can access your GitHub issues with the command line and you have an AI
chatbot that also uses a CLI. Why not write a little script that can summarize
key trends in issues, both for bug reports and enhancement requests? That can
help us identify what to focus on. Better yet, let’s automatically get those
summaries via email to help us stay on top of things!
We’re gonna generate something like this and save you from meetings, one email at a time.
Required doodads
You’ll need to have Pop and Mods installed to
use the provided script. Both of these programs also require environment
variables to be set. You can define these variables in the script, as
you’ll see in the example below.
Alternatively, you can set your environment variables in your
.bashrc/.zshrc, then source the file with a good ‘ol source ~/.zshrc in
your existing terminal session - note that any new sessions will use the
updated rc file anyway, so don’t worry about sourcing that file for new
sessions.
Because my dotfiles are public, I like to use Skate to protect my API
keys, so I don’t accidentally leak any secrets. Here’s how the two options
compare:
export OPENAI_API_KEY="" vs export OPENAI_API_KEY=$(skate get openai-key)
Under the hood
Mods
Mods
Built ItselfYep
AI on the command line.

Mods is a command line interface for interacting with AI chatbots, meaning,
it’s entirely script-friendly. It works with OpenAI-compatible endpoints and
LocalAI models. Mods uses GPT-4 by default and supports LocalAI models running
on port 8080. It falls back to using GPT-3.5 Turbo if GPT-4 isn’t available. If
you wanna learn more, you can read all about it.
For this script to work, you’ll need an OPENAI_API_KEY environment variable
set. Get your key.
Pop
Pop
EmailSent
Send emails from your terminal

Pop is a terminal-based program, offered as both a TUI and CLI, that allows you
to send emails from your terminal. All emails send through Resend
APIs or you can use a custom SMTP setup.
To use Pop with Resend you’ll need to export a RESEND_API_KEY, you can also
set RESEND_FROM to avoid having to type in your sending email. If you run
into any difficulties using your own domain with resend, you can always have it
send from onboarding@resend.dev.
export RESEND_API_KEY=$(pass RESEND_API_KEY)
export RESEND_FROM=pop@charm.sh
Alternatively, you can use a custom SMTP configuration with Pop.
export POP_SMTP_HOST=smtp.gmail.com
export POP_SMTP_PORT=587
export POP_SMTP_USERNAME=pop@charm.sh
export POP_SMTP_PASSWORD=hunter2
For this script to work, you’ll need the RESEND_API_KEY environment variable
or custom SMTP server configurations set. Get your key.
Putting it all together
Writing the script
Alright, now that you know how the whole thing works, let’s do something useful.
Set up the OPENAI_API_KEY environment variable.
Set up the RESEND_API_KEY environment variable (or configure your SMTP setup).
Run the following script and provide the path to a local git repository as an argument
#!/bin/sh

export RESEND_API_KEY=$(skate get resend)
export OPENAI_API_KEY=$(skate get open-ai)

# fail if no repo provided
if [ $# -ne 1 ]
then
    printf "Please provide an absolute path to a local code repository with a GitHub remote upstream."
    exit 1
else
    cd $1
    ( gh issue list |
    mods "what are recurring themes in bug reports given this output" && gh issue list |
    mods "what are recurring themes in enhancements given this output" ) |
    pop \
      --from onboarding@resend.dev \
      --to youremail@resend.dev \
      --subject $(basename $PWD)
fi
(PSSSST! basename $PWD provides the name of the project whose issues are
being summarized)
If you wanted these summaries to recur on a weekly basis (or whatever other
regular interval you’d like) you can choose to activate this script in a cron job.
Scheduling the script
Cron?!
Cron jobs are available on Unix-based systems and on Windows through a
Unix-based subsystem like WSL (Windows Subsystem for Linux). If you’re on a
Windows machine, you can also use Windows Task Scheduler to automate tasks, but
that is beyond the scope of this post.
Cron is a daemon to execute scheduled commands. By default, it runs in the
user’s home directory.
Crontabs are files that are used to schedule the execution of programs. These
files have all the instructions that you might need for the cron job to run.
Another, very popular alternative, is Systemd timer that also allows you to
schedule tasks. Cron is the more popular option, but can be hard to
troubleshoot by comparison to Systemd timers. If you’d like to learn more, you
can do so
here
Configuring cron
Run crontab -e to create a new crontab (use man crontab or tldr crontab).
The first iteration might look something like this:
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/bashbunni/go/bin:/usr/local/go:/home/bashbunni/go
GOPATH=$HOME/go
*/1 * * * * /home/bashbunni/scripts/repo-summary /home/bashbunni/charm/bubbletea >> /home/bashbunni/scripts/repo-summary.log 2>&1
Alas, there’s still room to improve. Try to spot the differences!
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/bashbunni/go/bin:/usr/local/go:/home/bashbunni/go
GOPATH=$HOME/go
*/1 * * * * repo-summary $HOME/charm/bubbletea >> /var/log/repo-summary/bubbletea.log 2>&1
To clean up the script, you have to run chmod +x repo-summary, and move the
executable to /usr/bin which allows the script to be executable from anywhere.
You’ll also want to move logging to /var/log which is typically where programs
post logs on Linux. If you’re not using Linux, you should change this to
whatever is idiomatic with your operating system. You need to change the
permissions on the /var/log/repo-summary directory with sudo chmod ugo+w /var/log/repo-summary so that the cron job has write access to the file.
That’s a fair amount of steps, so here’s that breakdown as a list:
chmod +x repo-summary
sudo mv repo-summary /usr/bin/repo-summary
sudo mkdir /var/log/repo-summary
sudo chmod ugo+w /var/log/repo-summary
You need sudo for some of these commands given that they’re in protected
directories.
Overengineering with containers?!
After spending a bunch of time getting this working in Docker, it turns out
it’s not worth containerizing given that it depends on a git repo to work. I
included this section anyway because I’m sure at least one developer will look
at this and say “I wonder if I could containerize it”… Just like I did.
Pros of a container:
User of the script gets a “plug-and-play” experience.
Export env variables from host to container.
Centralize dependency management.
How to containerize it
The deciding factor is that you need a local git repo to use with the script,
due to depending on the GitHub CLI results for mods to work. This gets
complicated when you containerize it. If you are curious to see what the
Dockerfile might look like, I’ve included it to indulge your curiosities.
FROM golang:1.21-alpine

# TODO Copy your own version of the script to run
# Don't forget, the file has to be in the same directory as the Dockerfile
COPY repo-summary /usr/bin/repo-summary
RUN chmod +x /usr/bin/repo-summary

# INSTALL DEPENDENCIES
ENV PATH="/usr/local/go/bin:${PATH}"

# Go apps
RUN go install github.com/charmbracelet/pop@latest
RUN go install github.com/charmbracelet/mods@latest

# gh cli
# If mods and pop were available through apk, we could have just used an alpine
# container instead of using the larger, go-alpine container.
RUN apk add github-cli
RUN rm /var/cache/apk/*

WORKDIR /home/bubbletea

CMD repo-summary
Then you can run it with
docker run -it -v $(pwd):/home/bubbletea -e
GH_TOKEN=$GH_TOKEN -e RESEND_API_KEY=$(skate get resend) -e
OPENAI_API_KEY=$(skate get open-ai)  repo-summary ./
Okay, okay, fine I’ll break down what that command does. You have to run
docker build --tag 'bubbletea-summary' . in the same directory as your
Dockerfile to create your custom image. Run the image as a container and
start an interactive terminal session in that container with -it. From there,
mount the desired repo as a volume (matches the WORKDIR specified in the
Dockerfile) with -v. Then pass along your environment variables from the host
machine to the container with -e. It’s important to provide the image ID,
which you can see with docker images. It will run the repo-summary script
in the WORKDIR of the container.
Notice that you need to define the environment variables needed by the
container as arguments to the docker run command. If you were to specify
these environment variables in the Dockerfile, then they would only be
accessible at build time, not during the lifespan of the container. (Thank you,
Ayman!)
If you want to challenge yourself, you can try to set up a cron job in the
docker container given the information provided. Let us know how you do!
Whatcha think?
Have some feedback on this post? We’d love to hear. Let us know in
Discord or via email at
vt100@charm.sh.


This is How We Do It
Christian Rocha — Wed, 06 Mar 2024 00:00:00 +0000
This is How We Do It
The Charm guide to building popular open source software
By Christian Rocha on 6 March 2024

If purple smoke and scratched up gold don't say success, I don’t know what does.
GitHub stars are a great indication of sentiment and adoption in open
source. On that note, we’re thrilled to announce that we’ve received our
100,000th star. We could not be more proud and we have you, the open source
community, to thank.
Here’s are some stats on how our ⭐️100k breaks down:
We’ve had 16 major releases with an average of ⭐️6.3k per release
Every major release has over ⭐️1k
Our open source projects are in use at companies like GitHub, Nvidia, AWS, Microsoft, Shopify, any many others
2022 yielded our highest star growth at ⭐️37k (137% yoy) thanks to the ardent response to Gum and VHS
4 of our projects (Glow, Gum, VHS, and Bubble Tea) have over ⭐️10k
Bubble Tea, our most-starred repo, clocks in at ⭐️23k
Bubble Tea is also our fastest growing repo, though it regained the lead only after Gum’s electrical-storm-like growth cooled down
How did we do it? Here’s the Charm open source playbook based on our collective
learnings over the past four years.
Wondering how we keep an eye on our repos’ ⭐️s? We have a
secret web page as well
as a super secret CLI command: curl https://stuff.charm.sh/stars.
Starting with a Problem
We always start with a problem of our own. This typically means a few key
factors are true:
We have firsthand knowledge of the problem and are thus well suited to solve it.
We are passionate about the problem. It’s a pain point we know personally and something we’re excited to solve for.
We have researched the problem and have found no worthy solutions, so our offering will be at least somewhat unique.
Bubble Tea, our text-based user interface framework, is a great example
of this. We wanted to be able to build ephemeral, user interfaces inline in the
terminal in go without having to concern ourselves with rendering, similar to
the experience we had building UIs in the browser with Elm. After a lot
of research we concluded that there was nothing in the go ecosystem that met
our needs so, out of pure necessity, we began work on what would become bubble
tea.
Bubble Tea is now our most popular project with ⭐️23k.
VHS, our terminal session recorder, is another great example. After
manually recording an enormous number of GIFs of terminal sessions we knew
there had to be a better way. While other good terminal recording
solutions existed, we found nothing scriptable, and nothing that produced
GIFs. Before we knew it we had a full blown scripting language (complete with
a tree sitter grammar) for
producing GIFs of terminal sessions.
VHS weighs in over ⭐️13k.
Bubble Tea
FlavorTaro
Build terminal user interfaces from the future, today.

VHS
GIFsGenerated
Create terminal GIFs with code!

Developer Experience
We build three types of things at charm: TUIs, CLIs and
libraries (called packages in Go). In all cases we believe an
exceptional user experience is paramount, and for that reason they’re not all
that different. After all, “developer experience” is really just user
experience. APIs and CLIs are user interfaces at the end of the day and they
require the same amount of care and thoughtfulness any good visual UI.
Regardless of the medium, we are striving for the one goal: an intuitive and
enjoyable experience for the person using the product.
The process is a bit like making an oil painting.
We start with a sketch, build a little bit, then test, evaluate, and adjust.
We’re constantly revisiting our design as the project develops, asking
ourselves if it’s still appropriate given how and where the project is
progressing.
Designing Libraries and APIs
Enjoying and getting value from an API is a visceral experience,
so we spent a lot of time and energy on getting the nuances right as the
design of the API is so key to adoption. Our goal is to produce an API that’s
intuitive, fun, and allows the developer to get a lot of value with as little
effort as possible.
We ask questions like:
How can we make this API easier to figure out?
How can we help developers avoid mistakes?
How can we design our API in a way that helps language servers provide effective completions?
Will this API lend it’s way to future innovations? Have we made room to grow?
Designing TUIs
I still can't believe this TUI runs over ssh.
TUIs bear many similarities to other visual types of user interfaces, but have
the wonderful, minimal quality of being just text—at one single size—and
color. We believe a good TUI can both exist in a long-running
fashion, like vim, as well as in an ephemeral manner that complements
the CLI experience, like fzf.
When designing TUIs we ask questions like the following:
Should this be inline, use the altscreen, or operate in both contexts?
How can we keep the user from ever wondering what key to press?
How should the application behave in very small terminal windows? What about very large terminal windows?
Does this really need to be a TUI, or would a CLI be more appropriate?
Designing CLIs

An old Betamax recording of one of our CLIs.
CLIs have the wonderful benefit of minimal user interface and the powerful
ability to tap into the essence of the command line with pipelines. The lack of
a GUI also means CLIs see faster development cycles, with the costs being
opaqueness and learning curve for the user.
When building CLIs we ask questions like the following:
Are these arguments and flags intuitive?
What do helpful error messages look like? How can error messages help users figure out how to use the product?
How can --help teach users how to get the most value out of this tool?
Can this CLI become more powerful by leaning into pipelines?
We also strive to provide manpage entries and completions for popular shells.
The README

The huh README is chock-full of examples and GIFs.
The README is critically important to the success of an open source
product. It’s often a developer’s first point of contact with a project and the
place where a developer will, in a matter of seconds, judge whether the project worthy of further
consideration. With this in mind, put a lot
of effort into README design, optimizing for strong first impressions.
Our strategy is to simply follow the age-old rule of advertising: showing the
product. Good products, when presented correctly, will sell themselves, which
is why we spend spend so much time on user experience and attention to detail.
With libraries, APIs, and packages we show the product with example code,
typically placing some code right at the top of the README. We want to show the
reader how intuitive, fun and powerful the API is and help them get started as
quickly as possible.
Do you want fries with that?
When it makes sense, we also insert GIFs of the product right at the top of the
README. While GIFs remain a technical nightmare in terms of a file format,
they’re the most effective medium we’ve encountered for illustrating how
software works in a concise manner. They’re short, silent videos that
automatically autoplay and automatically loop with no user interaction,
allowing us to paint a meaningful picture of the application in just a few
seconds.
As mentioned earlier, we believe so much in the effectiveness of GIFs that we
built vhs, a tool for scripting small, high quality GIFs of terminal
sessions.
Quick Reference
Beyond first impressions, we also tend to include a quick reference in our
READMEs to support the docs. The quick reference gives developers more insight
into the package, helps them get started, and highlights some of the common
parts of an API. It’s an excellent bridge to the docs that can help the user
make connections and gain insight into the API in ways the full, raw
documentation cannot.
In go projects, the README is also browsable in the generated documentation
(called GoDocs) so having the quick reference in the README is a win-win.
Examples, Examples, Examples

An example in the Harmonica README
We can’t emphasize the effectiveness of examples enough.
We’re very strong believers in learning by example and we believe code examples
are one of the best ways to learn about an API. They show developers how to use
the API in a concrete way and help them hit the ground running so they can be
more productive more quickly. Examples also serve as a cookbook, presenting the
developers with solutions to common use cases, whetting their appetites for
creative thinking with the product.
We commonly put a set of fully functional examples in a repository for users to
reference both online and locally in their clones. In many cases those examples
are what we ourselves used to help think about the product while we were
building it.
Branding
Good branding has the power to differentiate a product in the market with
a mere glance. Our strategy is to appeal to developers on a personal level and
create something that feels human, approachable, and memorable. We want the
branding to stand apart from the common efforts we see from the vast majority
of corporations and startups in the technology space. For that reason, we spend
a lot of time looking beyond tech and instead drawing inspiration from things
like video games, art, beauty,
Family Mart, Sanrio and so on.
The essence of our products’ branding is the name. Our goal is to disarm our
readers, suggest how they should feel about our product, and make them
smile. For these reasons an ideal Charm name is subversive, casual, and tongue
in cheek. Sometimes a good name comes quickly. Other times it takes
awhile. Because of this we start branding efforts early on in the product
development cycle.

Nothing says “handy CLI tool” like a pack of gum
After we’ve settled on a name we produce artwork. Good art goes beyond making
the product attractive: it equips both us and third parties with marketing
material for use in videos, articles, and so on. In order for third parties to
use the art, however, the art needs to be good. It needs to be something people
want to showcase. This is why we spend a lot of effort conceptualizing and
producing high quality art.


YouTubers using Gum art
Thinking Bigger
While we’re branding individual projects, we’re also playing the larger game of
increasing awareness of the Charm brand. Our goal is less about giving
individual projects a following, and more about promoting Charm as a consistent
producer of wonderful, open source software. A Charm product’s branding should
be consistent enough with other parts of the Charm narrative so it feels like
like a facet of the brand, yet unique enough so that it takes the brand to new
places.
Getting the Word Out
The bulk of of our launch efforts happen in the form of the prep described
above. If we’ve done the work correctly, we’ve built a good product and
prepared the necessary marketing material. There’s no magic in the launch
itself: we simply make the repository public and simply let people know. We
star it on GitHub, tell our friends, and post around the internet to the places
you’d expect: Twitter, Reddit,
Mastodon, and so on.
With any luck, the project starts to find its way around the internet. Maybe it
will get posted to Hacker News. Maybe it bubbles up onto to GitHub
Trending. Perhaps it’ll be picked up by Golang Weekly.
Maybe The Primeagen will mention it. Or maybe developers will find it
via more subtle means.
Embracing Open Source
In a lot of ways, a launch is when a project’s story really begins. Good open
source software has the unique ability to attract users, feedback, and
contributions en masse, so we put a significant effort into spending time
with the open source community post-launch.
Part of this is just paying attention. We look for patterns in feedback. We
think critically about what developers do with our projects, as well as what
they’re want to do, but can’t. We ask questions.
Another part of this is gracefully saying no. Sometimes the community will
excitedly request features or submit pull requests for things that don’t align
with our vision for the project. When saying no to a feature or pull request,
we’ve found the community generally understands that they don’t always have the
full context that we do. With this in mind, we always explain our reasons for
saying no, but we also keep listening because often we don’t have the context
that the community does.
For that reason, it’s equally important to say yes. Our biggest projects have
taken significant turns for the better exclusively via feedback and
contributions from the community. In some cases a single comment has inspired
critical changes to our work (“You know, if Bubble Tea worked this way then we
could…”) and in other cases we’ve received major, game-changing features and
optimizations from developers with incredible talent and skills far beyond our
expertise.
Sticking With It
The most important thing we can do for the project after putting it out into
the world is to continue working on it. Consistent work on an open source
project post-launch is, in fact, the most important factor the project’s
success. A big part of this, as mentioned earlier, is working with the
community. The rest is using the product, thinking about it, and continuing to
improve it. A launch is only the first step in a software project’s path to
maturity. It takes time, effort, and introspection for a project to reach its
full potential.
Actively maintaining open source projects also presents a sense of security to
developers. It suggests that the maintainer sees value in the project, that bug
reports will be honored, and feature requests will be entertained. It signals
to a developer that they can use the project and expect it to be relevant for
contemporary needs, and that they can expect a certain degree of support.
Bashbunni talks about Pop our CLI-based email tool.
In the same vein, we also keep promoting our work after launch. We’ll produce
short and long form video. We’ll talk about it in blog posts. We’ll feature
individuals and companies using the product. And every release, no matter how
small, is an opportunity to toot a project’s horn.
Sometimes our projects don’t take off immediately. Sometimes they’re not
met with the amount of acclaim we’d like. We know, however, that if we stick
with it, our software will find its way. Success doesn’t always come quickly
but it can always be found with enough persistence.


2023: That’s a Wrap!
Charm — Tue, 19 Dec 2023 00:00:00 +0000
2023: That’s a Wrap!
Sharing Charm’s 2023 highlights
By Charm on 19 December 2023
In the spirit of open source, we’re proud to share some 2023 milestones! This
year marked a year of open source growth and partnerships. To name a few
highlights, Bubble Tea, our TUI framework, crossed 20,000 GitHub
stars, we spoke at GitHub Universe, and we announced a
$6 million round of funding.
Here’s what that growth looks like in numbers:
Hot partnerships
We love working with other companies who share a similar passion for creative,
powerful, developer tooling. In the summer, we launched Pop,
in collaboration with Resend, to enable sending emails from the
terminal. Shortly thereafter we worked with Tailscale to expose
SSH endpoints on users’ Tailnets via Wish, our SSH framework, and
Wishlist, our SSH host directory. We also worked with CockRoachDB
to help make their interactive SQL Shell more powerful via Bubble Tea.
New launches and open source adoption in industry
We launched four new products this year:
Huh: a tool for building on the command line, with first-class support for screen readers
Mods: a tool that brings LLMs to the command line in a powerful, native way (pipes!)
Pop: a tool for sending emails from the terminal, built in collaboration with Resend
Log: the most bullet-proof, glamourous logger you’ve ever seen
Launch expanded our ability to reach new organizations and increase open source
adoption. Some of our favorite new products built with Charm technology are
Pulumi ESC, Datadog Agent, a daemon for collecting events
and metrics and sending them back to the Datadog mothership, and Truffle
Security, who announced an upgraded Trufflehog CLI at the Black Hat
Conference.
Bubble Tea continues to be our most popular library. There are 4,487 Bubble
Tea apps built to date, representing 119% growth compared to January this
year. And Glow, our glamorous markdown reading tool, continues to be
shared with over 53,000 users, a 55% increase since the beginning of 2023.
Connecting with the community
Our community continues to be our pride and joy. We ended 2022 at 65,000
GitHub stars. To date, we just crossed 95,000 GitHub stars! Most importantly,
we’ve continued to invest in engaging with our community online, which saw
a record 20% monthly increase across Twitter, YouTube, Discord, Mastodon,
Instagram. Our YouTube audience has more than doubled from that of last
year, with 5,800+ subscribers, racking over 243,000 views.
This month, we organized our first large community meetup in
collaboration with GitHub. Taking over GitHub’s HQ, we hosted 100+ developers,
founders, open source enthusiasts with Mario Kart, Ping Pong and Piñata-busting.
Charm × GitHub, San Francisco
2023 has been so, so fun. Here’s to 2024!


The Next Generation of the Command Line
Christian Rocha — Thu, 02 Nov 2023 00:00:00 +0000
The Next Generation of the Command Line
By Christian Rocha on 2 November 2023
We started Charm four years ago with the goal of making the command line
glamourous, powerful, fun and modern. Today we’re excited to announce that
we’ve raised $6MM led by Gradient, Google’s AI-focused venture fund, with
participation from new and existing investors Cavalry Ventures, Fuel Capital,
Firestreak Partners, as well as the founders of Supabase, Foursquare,
Fleetsmith (acquired by Apple), Honeycomb and others.
Charm started as a group of friends exchanging .vimrc tips and building open
source libraries. We have a background in consumer tech, with a focus on iOS
apps, but have always shared a passion for open source command line tools. We’d
spent a lot of time at companies like Apple, Last.fm, TweetDeck, Zenly, and The
Huffington Post building fun, UX forward products that users loved, and wanted
to bring that modern product thinking to the command line.
Why the command line? Why now?
The command line has been a ubiquitous platform for computing for the past 30+
years thanks, in part, to its focus on simple tools that do one thing well, the
ability to easily compose those tools into unique solutions, and a massive
library of existing command line programs from which to draw from. Many of
these attributes stand in stark contrast to the web and its siloed data, lack
of composability and large, opaque solutions that often include a healthy dose
of tracking, ads and other dark patterns.
The command line seemed to us like a healthy alternative to the web and closed
mobile platforms. It was also ripe for an update with a focus on user-centric
design and encrypted, self-hostable networked services. We wanted to build the
command line platform for the next 30+ years.
Why open source?
The command line and open source have a long history together and most of the
tools available for the command line are open source. It was important to us,
from the start, to stay open source and provide open source, self-hostable
solutions to our apps. We also love working with the open source community and
have built the team around amazing open source contributors.
Glow and Glamour
Glow uses Glamour to render markdown, obviously.
Our first two projects were Glow and Glamour. When we thought about modern
product development one thing we felt was lacking when building command line
apps was the separation of concerns between structure and style. On the web you
have HTML and CSS, specialized languages that allow for parallel
development. We wanted that on the command line so we built Glow and Glamour
around that concept.
Markdown is the true medium of developer expression.
Bubble Tea and Lip Gloss
Bubble Tea
FlavorTaro
Build terminal user interfaces from the future, today.

Lip Gloss
GlossinessVery
Your terminal style and layout toolkit.

While it was a great step forward to be able to style command line output based
on markdown structure, we needed a better framework for
interactivity. Christian, who has a background in Haskell and Elm, wanted a way
to build textual user interfaces in a stateful manner without having to think
about rendering. With that foundation, we created Bubble Tea, a TUI framework
for Go based on the Elm architecture. It ended up being a great pairing of
functional programming concepts and Go’s less functional nature.
This allowed us to easily build animated, reactive, TUI-based applications. We
saw amazing adoption of Bubble Tea and it now powers over 4,000 apps, boasts 20k
stars on GitHub, and is in use at major companies like AWS, NVIDIA, Microsoft
Azure, and many others.
“Would it be weird to make this progress bar bounce?” we wondered.
After building a couple formidable Bubble Tea applications we also realized we
also needed first class styling and layout tools. Lip Gloss was born and is the
layout engine for not only nearly every Bubble Tea TUI, but also many general
purpose CLI-based tools. Over 4,800 open source tools use Lip Gloss to date.
Our studies show devs who build terminal stuff like weird mascots.
SSH, Wish, and Soft Serve
Wish
MagicalYes
Make SSH apps, just like that!

Soft Serve
ConsistencySmooth
The mighty, self-hostable Git server for the command line

With our TUI tooling solidly in-place, we started to think about designing
command line first APIs for services. We settled on using SSH as our
protocol. Using SSH keys, we could offer seamless API access without passwords,
with anonymity and end-to-end encryption. We could even bridge identity to HTTP
based APIs with JWTs. This led to the development of Wish and the Charm Cloud,
both of which leverage SSH based APIs and power the backend to tools like Glow
and Skate.
Another advantage of the SSH protocol is that you can use it interactively with
a TUI streamed from the server. With Wish, we made it easy to plug a Bubble Tea
application into an SSH server and stream the TUI remotely. That along with
Git’s support for SSH allowed us to build Soft Serve, self-hostable Git server
with a first-class TUI.
Gum and VHS

Non-toxic?
Two of our latest releases have focused on bringing our platform not just to Go
developers but to people writing scripts and using shells. Gum takes many of
the Bubbles from our Bubble Tea component library as well as styling and layout
feature from Lip Gloss, and creates a single binary that makes it super easy to
add interactive UI, input elements, and styling and layout to your scripts and
shell pipelines and quickly apply advanced. It’s our fastest growing project to
date.
VHS
GIFsGenerated
Create terminal GIFs with code!

VHS is a tool that lets you elegantly script and record screencasts of command
line apps and render them as GIFs. It’s something we built for ourselves so we
could make recordings in our READMEs and social media posts but it’s found wide
adoption in the community.
A pair of hockey sticks.
Why Gradient
Red, white and awesome.
From our very first conversation with Darian, we knew that we had found
a partner that shared our long term vision for the command line, respect for
the developer community and passion for open source. Gradient and Darian felt
like the best possible partners to help us take Charm to the next level and
we’re excited to be part of the Gradient family.
What’s next
We’ve been working on the next generation of our platform on both the frontend
and backend. Over the next couple of months we’ll begin rolling out alpha tests
of major updates to our projects and platform. We’ll also be working on
sustainable open source software development and ethical monetization.
We want to work closely with the community on the future of Charm and the
command line, so please join us on Discord or sign up via email below
for our next alpha launch.





Soft Serve now supports Git LFS and More!
Ayman Bagabas — Mon, 21 Aug 2023 00:00:00 +0000
Soft Serve now supports Git LFS and More!
By Ayman Bagabas on 21 August 2023
Soft Serve
ConsistencySmooth
The mighty, self-hostable Git server for the command line

At Charm, we use Git LFS all the time to bring large files into version control. This very website uses Git LFS to manage video and image assets in the repository and download them during the deployment pipeline. Git LFS stands for “Git Large File Storage” and it is widely supported by many open source and commercial servers.
Git LFS works by using text pointers inside Git repositories while storing the actual file contents on a different server (for example, S3).
In this release, we are pleased to introduce not only Git LFS support, but also collaborator access levels, HTTP authentication, and Postgres database support. Read on for details!
Git LFS Support Over HTTP and SSH
You can now leverage Git LFS in Soft Serve to manage large files over both HTTP and SSH transports, allowing you to handle large files within your repositories without unnecessarily bogging down your clones. Git LFS API relies on a separate HTTPS server to handle transferring the files. The pure-SSH transfer protocol was introduced in Git LFS v3.0. Soft Serve supports both protocols.
git lfs track *.png
git add -A
git push origin main
Soft Serve also supports Git LFS locks.
# As user "tomato" we run
git lfs lock path/to/file
git lfs locks
# path/to/file	tomato	ID:1
Collaborator Access Levels
Adding collaborators is more flexible than ever. Now, you can assign a specific access level to repository collaborators. All you need to do is specify the access level in your repo collab command.
Let’s say you want to make a user read a private repository without giving them the ability to push files and make changes. You could do so by adding a new collaborator with read-only access. To add a collaborator frankie to the repo foobar:
ssh git.example.com repo collab add foobar frankie read-only
Imagine you want to make frankie read all the repositories under docs, you could do something like this:
repos=$(ssh git.example.com repo ls | grep "^docs/") # Get all the repos under docs/
while IFS= read -r repo; do
    ssh git.example.com repo collab add $repo frankie read-only
done <<< $repos
Here, the access level parameter is optional and defaults to read-write access when not specified.
HTTP Authentication
Whether you use Git over HTTP(s), SSH, or both, Soft Serve has you covered. You can use user access tokens to authenticate over HTTP(s). Use the SSH token command to manage your access tokens. Then use the generated tokens as either your HTTP username or password to authenticate and access your repositories.
To generate a new token:
ssh git.example.com token create 'my new token'
# ss_1234abc56789012345678901234de246d798fghi

# Or with an expiry date
ssh git.example.com token create --expires-in 1y 'my other token'
# ss_98fghi1234abc56789012345678901234de246d7
For example, to clone a private repository fajitas with an access token:
git clone https://ss_4db594cxxxxxx@git.example.com/fajitas.git
Postgres
You can now use Postgres instead of SQLite to store persistent data. SQLite is great for a simple and lightweight applications. If you’re using Soft Serve as a single user, perhaps SQLite is all you need. However, if you want to use a more powerful and scalable database engine, Postgres has your back.
Soft Serve uses SQLite as its default database engine. To use Postgres instead, first create a new database for Soft Serve. Then configure Soft Serve to use Postgres as its database engine.
# Create a Soft Serve database
psql -hlocalhost -p5432 -Upostgres -c 'CREATE DATABASE soft_serve'
Now once you have a Soft Serve database, configure your server to use Postgres. In your config.yaml, head to the db section to configure your database settings. Add the section if it doesn’t exist.
db:
  driver: "postgres"
  data_source: "postgres://postgres@localhost:5432/soft_serve?sslmode=disable"
Or if you’re using environment variables to configure your server:
SOFT_SERVE_DB_DRIVER=postgres \
SOFT_SERVE_DB_DATA_SOURCE="postgres://postgres@localhost:5432/soft_serve?sslmode=disable" \
soft serve
For more information, see Soft Serve Database Configuration.
Other Enhancements
Along with all these great features, Soft Serve v0.6 brings lots of bug fixes, better error handling, and improved performance. Check out the release page for a full list of changes.
What are you waiting for! Head to the Soft Serve releases page to grab the latest release.
Soft Serve
ConsistencySmooth
The mighty, self-hostable Git server for the command line




Wishlist Endpoint Discovery
Carlos Becker
Wishlist Endpoint Discovery
By Carlos Becker on 19 Jul 2023
We just added endpoint discovery to Wishlist, our SSH host directory.
Wishlist
ConvenientVery
Your SSH directory.

Wishlist can act as a bastion,
presenting the user with a list of hosts they can SSH into from that host.
You can also run it locally, in which case it becomes a TUI (text-based
user interface) for your ~/.ssh/config (or to a predefined list of hosts in
a YAML configuration file).
But there’s more to it: did you know you can discover hosts from several
sources?
Endpoint Discovery
Currently, we support the following sources:
DNS SRV records
Zeroconf with mDNS
Tailscale
Let’s see how it works, shall we?
Tailscale
We partnered with our friends at Tailscale to add
endpoint discovery to Wishlist. Check out what they have to say about it
here.
Tailscale is a VPN service that makes devices and
applications you own securely accessible anywhere in the world.
It uses the WireGuard protocol, and has apps for
pretty much all platforms.
To discover your Tailscale-connected machines, you’ll need an
API Access Token,
and the name of your tailnet.
With that information in hand, run wishlist with --tailscale.key
(or set $TAILSCALE_KEY) and --tailscale.net, for example:
wishlist --tailscale.net=charm --tailscale.key=ts-key-aaabbb...
And that’s it! Wishlist will discover all your tailnet’s machines on startup.
Note: We can’t get the open ports through the API, so all endpoints
discovered will use the default SSH port (22).
You can change that with hints.
It’s also worth mentioning that Tailscale’s API keys expire after 90 days (max).
To avoid the trouble of having to change the key every couple of months,
you can also use their beta
OAuth Clients.
Create an app with devices:read scope
here, and run with:
wishlist --tailscale.net=charm \
  --tailscale.client.id=aaabbb... \
  --tailscale.client.secret=tskey-client-aaaabbb...
This also gives Wishlist a more restricted access: only reading the device list,
nothing else.
Zeroconf with mDNS
Zeroconf enables service discovery in a network
without any operator intervention.
It was originally adapted from AppleTalk, circa 1997, and is tracked by
the RFC 6762.
If you run anything Apple in your network, chances are they are all already
available in .local domains.
This happens because Apple devices employ
Bonjour (a Zeroconf implementation)
which is installed and configured by default.
On Linux, you can use either Avahi or
SystemD for the same purpose.
For Avahi, installing and enabling the daemon (the package is usually named
avahi-daemon) will make your host available in the network as hostname.local.
To make the host available in Wishlist, though, you’ll need to expose a
_ssh._tcp service.
You can do that by creating the file /etc/avahi/services/ssh.service with the
following contents:



   replace-wildcards="yes">%h
  
    _ssh._tcp
    22
  

You can check if you have any available endpoints by running:
# on Linux:
avahi-browse --domain local _ssh._tcp

# on macOS:
dns-sd -B _ssh._tcp
All that being said, you can run wishlist with --zeroconf.enabled, and it’ll operate using sensible defaults:
wishlist --zeroconf.enabled
Run wishlist --help | grep zeroconf to see all options.
DNS SRV
Service Records (SRV)
are specified in DNS for defining the host name and port number of servers
for specific services.
It is defined as:
_service._proto.name. ttl IN SRV priority weight port target
Wishlist will look for records with _ssh._tcp as service and proto.
You can mimic what it’ll do with dig, e.g. for the caarlos0.dev domain:
dig SRV _ssh._tcp.caarlos0.dev +short
So, for instance, if I want to expose a SRV record on port 2244,
I would add an entry like this to my DNS:
_ssh._tcp.caarlos0.dev. 300 IN SRV 10 2 2244 192.168.1.123.
Once you’ve done that, you can run wishlist setting --srv.domain to
make it query the your name server and list the SRV records as endpoints.
For example:
wishlist --srv.domain=caarlos0.dev
Hints
You might be asking yourself: “What if I want to set some more advanced
options in these endpoints?” That’s what hints are for.
Hints have a similar structure to the endpoints setting, but they work
differently: if a hint doesn’t match a discovered endpoint, it won’t get
added to the final endpoint list, whereas regular endpoints would.
It works by using a match field (which can be a glob), and then tries
to match all discovered endpoints hostnames with it.
If it matches, the options in that hint will be set onto the final endpoint.
You can set port (especially useful with Tailscale), link, user,
description, and more.
Here’s an example showing all available fields:
hints:
  - match: "*.local"
    port: 23234
    description: "A description of this endpoint.\nCan have multiple lines."
    user: notme
    remote_command: uptime -a
    forward_agent: true
    request_tty: true
    connect_timeout: 10s
    proxy_jump: user@host:22
    link:
      name: Optional link name
      url: https://github.com/charmbracelet/wishlist
    identity_files:
      - ~/.ssh/id_ed25519
      - ~/.ssh/charm_id_ed25519
    set_env:
      - FOO=bar
      - BAR=baz
    send_env:
      - LC_*
      - LANG
      - SOME_ENV
You can see the full, commented out, configuration file
here.
Once you have your configuration file, run wishlist passing its path
to --config.
Wishlist will then discover all the endpoints (through all options available),
and then, if there are any hints, iterate through them and apply
them to the discovered nodes.
Finally, on server mode, you can specify a --endpoints.refresh.interval,
so Wishlist will re-discover the nodes and also reload the configuration file,
re-applying the hints too.
We believe that those features will make your Wishlist-powered SSH directories
easier to maintain and to use, and can’t wait to see what you’ll do with it.


Email in your terminal
Maas Lalani — Mon, 17 Jul 2023 00:00:00 +0000
Email in your terminal
By Maas Lalani on 17 July 2023
Introducing Pop
Pop
EmailSent
Send emails from your terminal

At Charm, we love the terminal. We also send lots of emails. So, we thought it
would be awesome to have a way to send emails from the terminal. Of course, this
hypothetical tool would need to support markdown formatting and file
attachments.
So, we built Pop, a tool to send email
from the terminal. Pop supports markdown-based formatting, file attachments, and
has a command-line interface for when you need to write scripts.
Watch how quickly you can send an email, without ever leaving your terminal:
Even quicker with the command-line interface:
If you pass flags to pop but it’s not enough to send a valid email, pop will
launch the TUI with the flags passed as pre-populated values.
Powered by Resend
We partnered with our friends at Resend to launch Pop.
All emails send through Resend APIs under-the-hood. This
lets you send emails from custom domains and manage your sent emails from their
web interface if necessary.
To use Pop, you’ll need to export a
RESEND_API_KEY, you can also set RESEND_FROM to avoid having to type in your
sending email.
export RESEND_API_KEY=$(pass RESEND_API_KEY)
export RESEND_FROM=pop@charm.sh
Feedback
Send us your feedback (with Pop) and tell us what you think:
vt100@charm.sh


Recipe: Let’s Build a Kaomoji Generator
Christian Rocha — Mon, 22 May 2023 00:00:00 +0000
Recipe: Let’s Build a Kaomoji Generator
By Christian Rocha on 22 May 2023

This is what we’re gonna make.
Before the emoji there was the Kaomoji. A bunch of rando unicode letters smashed
together to create cute, little images.
ʕっ•ᴥ•ʔっ Like a bear reaching out to hug you.
｡:ﾟ(｡ﹷ ‸ ﹷ ✿) Or a pouty child with a flower in her hair.
((งง •̀•̀__•́•́))งง Or a dude who is so ready to get into a fight that he’s shaking with fury.
Like internet snowflakes, Kaomojis have seemingly infinite number of
permutations. You could have an angry bear doing a table flip, or a melancholy
man tossing stars to the wind.
But honestly, who has the time to come up with these? Or to research the best
ones? Computers do, that’s who. So we’re gonna build a little Kaomoji generator
with Mods, Gum, and bash.
Mods
The modchip of AI.
The keystone to all this is Mods, an open source tool that brings AI to
the command line. It’s especially good with pipelines and generally working
with other commmand line tools in true unix fashion. You can install it
here.
You’ll also want to install Gum.
The script
So let’s get to it already. The basic approach we’re taking is:
Ask mods to generate some Kaomojis
Use gum to pick one
Copy the Kaomoji to the clipboard
And here’s how we’re doing it:
#!/usr/bin/env bash

# If the user passes '-h', '--help', or 'help' print out a little bit of help.
# text.
case "$1" in
	"-h" | "--help" | "help")
        printf 'Generate kaomojis on request.\n\n'
        printf 'Usage: %s [kind]\n' "$(basename "$0")"
        exit 1
        ;;
esac

# The user can pass an argument like "bear" or "angry" to specify the general
# kind of Kaomoji produced.
sentiment=""
if [[ $1 != "" ]]; then
	sentiment=" $1"
fi

# Ask mods to generate Kaomojis. Save the output in a variable.
kaomoji="$(mods "generate 10${sentiment} kaomojis. number them and put each one on its own line.")"
if [[ $kaomoji == "" ]]; then
	exit 1
fi

# Pipe mods output to gum so the user can choose the perfect kaomoji. Save that
# choice in a variable. Also note that we're using cut to drop the item number
# in front of the Kaomoji.
choice="$(echo "$kaomoji" | gum choose | cut -d ' ' -f 2)"
if [[ $choice == "" ]]; then
	exit 1
fi

# If xsel (X11) or pbcopy (macOS) exists, copy to the clipboard. If not, just
# print the Kaomoji.
if command -v xsel &> /dev/null; then
	printf '%s' "$choice" | xclip -sel clip # X11
elif command -v pbcopy &> /dev/null; then
	printf '%s' "$choice" | pbcopy # macOS
else
	# We can't copy, so just print it out.
	printf 'Here you go: %s\n' "$choice"
	exit 0
fi

# We're done!
printf 'Copied %s to the clipboard\n' "$choice"
To execute the script just call it with bash:
$ bash kaomoji
Or make the script executable and call it directly:
$ chmod +x ./kaomoji
$ ./kaomoji
Going further
How would you improve this script? Here are a few ideas:
Add an argument to specify the number of Kaomojis generated
Let the user choose more than one Kaomoji with gum choose --no-limit
Colorize the output with gum style
Save your fave Kaomojis to a Skate database
Whatcha think?
Have some feedback on this post? We’d love to hear. Let us know in
Discord or via email at vt100@charm.sh.


Writing Bubble Tea Tests
Carlos Becker — Mon, 08 May 2023 00:00:00 +0000
Writing Bubble Tea Tests
By Carlos Becker on 8 May 2023
Last week we launched our github.com/charmbracelet/x repository,
which will contain experimental code that we’re not ready to promise any
compatibility guarantees on just yet.
The first module there is called teatest.
It is a library that aims to help you test your Bubble Tea apps.
You can assert the entire output of your program, parts of it, and/or its
internal tea.Model state.
In this post we’ll add tests to an existing app using current’s teatest
version API.
The app
Our example app is a simple sleep-like program, that shows how much time
is left. It is similar to my timer TUI, if you’re interested in
something more complete.
Without further ado, let’s create the app.
First, navigate
here to
create a new repository based on our
bubbletea-app-template
repository.
Then clone it. In my case, I called it teatest-example:
gh repo clone caarlos0/teatest-example
cd teatest-example
go mod tidy
$EDITOR .
This example will just sleep until the user presses q to exit.
With a few modifications we can get what we want:
Add a duration time.Duration field to the model. We’ll use this to keep
track of how long we should sleep.
Add a start time.Time field to the model to mark when we started the
countdown.
The initialModel needs to take the duration as an argument. Set it into the
model, as well as setting start to time.Now().
Add a timeLeft method to the model, which calculates how long we still
need to sleep.
In the Update method, we need to check if that timeLeft > 0, and quit
otherwise.
In the View method, we need to display how much time is left.
Finally, in main we parse os.Args[1] to a time.Duration and pass it down
to initialModel.
And that’s pretty much it. Here’s the
link to the full diff.
Imports
Before anything else, we need to import the teatest package:
go get github.com/charmbracelet/x/exp/teatest@latest
The full output test
Next let’s create a main_test.go and start with a simple test that asserts
the entire final output of the app.
Here’s what it looks like:
// main_test.go
func TestFullOutput(t *testing.T) {
	m := initialModel(time.Second)
	tm := teatest.NewTestModel(t, m, teatest.WithInitialTermSize(300, 100))
	out, err := io.ReadAll(tm.FinalOutput(t))
	if err != nil {
		t.Error(err)
	}
	teatest.RequireEqualOutput(t, out)
}
We created a model that will sleep for 1 second.
We passed it to teatest.NewTestModel, also ensuring a fixed terminal size
We ask for the FinalOutput, and read it all.
Final means it will wait for the tea.Program to finish before
returning, so be wary that this will block until that condition is met.
We check if the output we got is equal the output in the golden file.
If you just run go test ./..., you’ll see that it errors. That’s because we
don’t have a golden file yet. To fix that, run:
go test -v ./... -update
The -update flag comes from the teatest package. It will update the
golden file (or create it if it doesn’t exist).
You can also cat the golden file to see what it looks like:
> cat testdata/TestFullOutput.golden


    ⣻  sleeping 0s... press q to quit

In subsequent tests, you’ll want to run go test without the -update, unless
you changed the output portion of your program.
Here’s the link to the full diff.
The final model test
Bubble Tea returns the final model after it finishes running, so we can also
assert against that final model:
// main_test.go
func TestFinalModel(t *testing.T) {
	tm := teatest.NewTestModel(t, initialModel(time.Second), teatest.WithInitialTermSize(300, 100))
	fm := tm.FinalModel(t)
	m, ok := fm.(model)
	if !ok {
		t.Fatalf("final model have the wrong type: %T", fm)
	}
	if m.duration != time.Second {
		t.Errorf("m.duration != 1s: %s", m.duration)
	}
	if m.start.After(time.Now().Add(-1 * time.Second)) {
		t.Errorf("m.start should be more than 1 second ago: %s", m.start)
	}
}
The setup is basically the same as the previous test, but instead of the asking
for the FinalOutput, we ask for the FinalModel.
We then need to cast it to the concrete type and then, finally, we assert for
the m.duration and m.start.
Here’s the link to the full diff.
Intermediate output and sending messages
Another useful test case is to ensure things happen during the test.
We also need to interact with the program while its running.
Let’s write a quick test exploring these options:
// main_test.go
func TestOuput(t *testing.T) {
	tm := teatest.NewTestModel(t, initialModel(10*time.Second), teatest.WithInitialTermSize(300, 100))

	teatest.WaitFor(t, tm.Output(), func(bts []byte) bool {
		return bytes.Contains(bts, []byte("sleeping 8s"))
	}, teatest.WithCheckInterval(time.Millisecond*100), teatest.WithDuration(time.Second*3))

	tm.Send(tea.KeyMsg{
		Type:  tea.KeyRunes,
		Runes: []rune("q"),
	})

	tm.WaitFinished(t, teatest.WithFinalTimeout(time.Second))
}
We setup our teatest in the same fashion as the previous test, then we assert
that the app, at some point, is showing sleeping 8s, meaning 2 seconds have
elapsed. We give that condition 3 seconds of time to be met, or else we fail.
Finally, we send a tea.KeyMsg with the character q on it, which should cause
the app to quit.
To ensure it quits in time, we WaitFinished with a timeout of 1 second.
This way we can be sure we finished because we send a q key press, not because
the program runs its 10 seconds out.
Here’s the link to the full diff.
The CI is failing. What now?
Once you push your commits GitHub Actions will test them and likely fail.
The reason for this is because your local golden file was generated with
whatever color profile the terminal go test was run in reported while GitHub
Actions is probably reporting something different.
Luckily, we can force everything to use the same color profile:
// main_test.go
func init() {
	lipgloss.SetColorProfile(termenv.Ascii)
}
In this app we don’t need to worry too much about colors, so its fine to use the
Ascii profile, which disables colors.
Another thing that might cause tests to fail is line endings. The golden files
look like text, but their line endings shouldn’t be messed with—and git might
just do that.
To remedy the situation, I recommend adding this to your .gitattributes file:
*.golden -text
This will keep Git from handling them as text files.
Here’s the link to the full diff.
Final words
This is an experimental, work in progress library, hence the
github.com/charmbracelet/x/exp/teatest
package name.
We encourage you to try it out in your projects and report back what you find.
And, if you’re interested, here’s the link to the repository for this
post.


Self-hosted Soft Serve
Ayman Bagabas — Fri, 28 Apr 2023 00:00:00 +0000
Self-hosted Soft Serve
By Ayman Bagabas on 28 April 2023
Soft Serve is a self-hostable Git server for the command-line. It supports Git over HTTP(s), SSH, and the Git Protocol. Soft Serve also comes with a simple straight-forward user management interface for teams.
In this post, we will go through how to set up your Soft Serve instance. This includes setting up SSH access, HTTPS using Certbot, and how to manage your Soft Serve instance.
Prerequisites
In this post, we are assuming that you have a basic knowledge of networking, a general understanding of how to use Linux and the command-line, and are comfortable using git commands.
You will need:
A server to run Soft Serve on.
A domain name to access your server (optional).
If you’re using a cloud provider, make sure you have the right access settings before proceeding i.e. access tokens. Running Soft Serve locally or on-premise will vary depending on your setup. This post will only cover setting up Soft Serve on the host server using Systemd, reroute OpenSSH traffic, and set up Certbot for HTTPS.
We will be using a virtual machine running Ubuntu 22.04 hosted on the cloud. Many cloud providers provide virtual machine services. DigitalOcean calls them Droplets. EC2 if you’re using AWS.
Note: make sure you enable access to the server and add any firewall rules. Soft Serve uses ports 23231/tcp (SSH), 23232/tcp (HTTP), and 9418/tcp (Git). We will reconfigure Soft Serve to run on port 22/tcp (SSH) and 443/tcp (HTTPS), then use port 2200/tcp for OpenSSH shell access.
Setting Up Soft Serve
We will start by installing Soft Serve from Charm’s APT repository, setting up a Systemd service, getting a Let’s Encrypt certificate using Certbot, and lastly, reconfiguring OpenSSH to access the shell on an alternate port (since Soft Serve will be using the default SSH port). Let the fun begin!
Installing Soft Serve
Soft Serve and all other Charm tools can be installed via APT/RPM repositories. Check out the installation section for more options. Since we’re using Ubuntu, we can install Soft Serve from the Charm APT repository:
# Retrieve and import repository key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
# Add APT repository source
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
# Install Soft Serve & git
sudo apt update && sudo apt install soft-serve git
You’re all set! You should now be able to run the soft binary.
soft --version
Now that we have Soft Serve installed, let’s run it locally.
soft
Soft Serve is a self-hostable Git server for the command line.

Usage:
  soft [command]

Available Commands:
  help           Help about any command
  serve          Start the server

Flags:
  -h, --help      help for soft
  -v, --version   version for soft

Use "soft [command] --help" for more information about a command.
To start the server, we can run soft serve. This will create a data directory that will store the repositories and database.
2023-04-28 server: Starting Git daemon addr=:9418
2023-04-28 server: Starting HTTP server addr=:23232
2023-04-28 server: Starting SSH server addr=:23231
2023-04-28 server: Starting Stats server addr=:23233
Well, well, we now have a running Soft Serve instance! But, this would be tedious to run each time our server restarts. Luckily, systemd can help us start the process on boot.
Systemd
Create a file under /etc/systemd/system/soft-serve.service and put your Systemd service configuration. Here we will be running Soft Serve as root to simplify things. We will place the server’s data under /var/local/lib/soft-serve. Make sure you have added your SSH authorized key to the SOFT_SERVE_INITIAL_ADMIN_KEYS environment variables. You can remove this later once the “admin” user is created and has your key.
For a full list of Soft Serve server settings and environment variables refer to the Server Settings section.
[Unit]
Description=Soft Serve git server 🍦
Documentation=https://github.com/charmbracelet/soft-serve
Requires=network-online.target
After=network-online.target

[Service]
Type=simple
Restart=always
RestartSec=1
ExecStartPre=mkdir -p /var/local/lib/soft-serve
ExecStart=/usr/bin/soft serve
Environment=SOFT_SERVE_DATA_PATH=/var/local/lib/soft-serve
Environment=SOFT_SERVE_INITIAL_ADMIN_KEYS='ssh-ed25519 AAAAC3NzaC1lZDI1...'

[Install]
WantedBy=multi-user.target
Now, reload Systemd configuration, enable and start the service.
sudo systemctl daemon-reload
sudo systemctl enable soft-serve.service
sudo systemctl start soft-serve.service
We can check the logs using journalctl -u soft-serve.service.
Tip: add -f flag to “tail” the logs as they appear. Useful when using tmux to keep an eye on logs journalctl -fu soft-serve.service.
HTTPS Certificate
To be able to use HTTPS in Soft Serve, we will need to set up TLS certificates so that Soft Serve can use an encrypted connection to communicate with the world. We will be using Certbot to issue us Let’s Encrypt certificates. Following Certbot instructions, we will choose Other and Ubuntu 20 for the instruction options.
Note: if you’re not using a domain name, you won’t be able to issue an HTTPS certificate since Let’s Encrypt doesn’t allow the use of bare IP addresses. ZeroSSL is a great alternative that supports bare IP addresses.
Now, make sure you have updated your DNS records to point your server’s IP address to your custom domain. This is typically done using a A record. This will vary depending on your DNS domain provider. We will be using git.example.com to demonstrate issuing a certificate for the subdomain git.
Install the certbot cli tool using snapd to issue the certificate for our domain.
# Stop Soft Serve
sudo systemctl stop soft-serve.service
# Install certbot from snapd
sudo snap install --classic certbot
# Issue certificate
sudo certbot certonly --standalone
# Enter your email address
# Agree for terms of service
# Enter your domain(s): git.example.com
Voilà, we have an HTTPS certificate!
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/git.example.com/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/git.example.com/privkey.pem
This certificate expires on 2023-07-28.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
 * Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
 * Donating to EFF:                    https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Once we have our certificate, we will need to update our Soft Serve configuration to use them and point to our new https:// address.
Server Configuration
Soft Serve stores its server configuration in the config.yaml file under the data directory. By default, it uses the relative path data as a data directory. You can override this by defining a SOFT_SERVE_DATA_PATH environment variable (as seen above in the systemd service file). This means that our config.yaml file lives under /var/local/lib/soft-serve since we have that as our data directory path.
To use HTTPS default port (443), we have to tell Soft Serve about our Let’s Encrypt certificates. And since we are using a custom domain now, we need to update the server’s public URL. This is the address that will you will be using to manage user access and git clone repositories. Lastly, we will make OpenSSH use a different port, so we can still have shell access on our remote host.
Info: you can override configuration settings using environment variables. For example, to override the server’s name add SOFT_SERVE_NAME='Git Melon' to your soft-serve.service file.
Let’s edit the file and see what’s in there 🤔
# Make sure you have $EDITOR defined
# Use vim <3
# export EDITOR=vim
sudo $EDITOR /var/local/lib/soft-serve/config.yaml
Here, we can see the default server configurations.
Change the ssh.listen_addr to use the default SSH port (22).
Use ssh://git.example.com as our ssh.public_url (this will be used for clones over SSH e.g. git clone git@git.example.com:repo.git).
Change the http.listen_addr to use HTTPS default port (443).
Update http.public_url to point to use https:// and point to our custom domain https://git.example.com.
Set http.tls_key_path and http.tls_cert_path to use the generated Let’s Encrypt certificates.
The final configurations look like this:
# Soft Serve Server configurations

# The name of the server.
# This is the name that will be displayed in the UI.
name: "Soft Serve"

# Log format to use. Valid values are "json", "logfmt", and "text".
log_format: "text"

# The SSH server configuration.
ssh:
  # The address on which the SSH server will listen.
  listen_addr: ":22"

  # The public URL of the SSH server.
  # This is the address that will be used to clone repositories.
  public_url: "ssh://git.example.com"

  # The path to the SSH server's private key.
  key_path: "ssh/soft_serve_host"

  # The path to the server's client private key.
  # This key will be used to authenticate the server to make git requests to
  # ssh remotes.
  client_key_path: "ssh/soft_serve_client_ed25519"

  # The maximum number of seconds a connection can take.
  # A value of 0 means no timeout.
  max_timeout: 0

  # The number of seconds a connection can be idle before it is closed.
  idle_timeout: 0

# The Git daemon configuration.
git:
  # The address on which the Git daemon will listen.
  listen_addr: ":9418"

  # The maximum number of seconds a connection can take.
  # A value of 0 means no timeout.
  max_timeout: 0

  # The number of seconds a connection can be idle before it is closed.
  idle_timeout: 3

  # The maximum number of concurrent connections.
  max_connections: 32

# The HTTP server configuration.
http:
  # The address on which the HTTP server will listen.
  listen_addr: ":443"

  # The path to the TLS private key.
  tls_key_path: "/etc/letsencrypt/live/git.example.com/privkey.pem"

  # The path to the TLS certificate.
  tls_cert_path: "/etc/letsencrypt/live/git.example.com/fullchain.pem"

  # The public URL of the HTTP server.
  # This is the address that will be used to clone repositories.
  # Make sure to use https:// if you are using TLS.
  public_url: "https://git.example.com"

# The stats server configuration.
stats:
  # The address on which the stats server will listen.
  listen_addr: "localhost:23233"
# Additional admin keys.
#initial_admin_keys:
#  - "ssh-rsa AAAAB3NzaC1yc2..."
This looks good so far. Now before we start Soft Serve up again, we need to change the port that OpenSSH uses. This is specified in /etc/ssh/sshd_config.
sudo $EDITOR /etc/ssh/sshd_config
# Uncomment `#Port 22`
# Change `Port 22` to `Port 2200`
# Or use the power of `sed` :)
sudo sed -i 's/^#Port 22/Port 2200/g' /etc/ssh/sshd_config
# Restart sshd
sudo systemctl restart sshd
You can now access your server’s shell on port 2200. Try it out: ssh -i  -p 2200 git.example.com.
Now, let’s start our Soft Serve server again.
sudo systemctl start soft-serve.service
View logs using journalctl -fu soft-serve.service. Verify the server is indeed running on :22 and :443.
Apr 28 20:33:39 ip-172-31-84-249 soft[7594]: 2023-04-28 server: Starting Git daemon addr=:9418
Apr 28 20:33:39 ip-172-31-84-249 soft[7594]: 2023-04-28 server: Starting HTTP server addr=:443
Apr 28 20:33:39 ip-172-31-84-249 soft[7594]: 2023-04-28 server: Starting SSH server addr=:22
Apr 28 20:33:39 ip-172-31-84-249 soft[7594]: 2023-04-28 server: Starting Stats server addr=localhost:23233
Manage Soft Serve
Now that we successfully set up our Soft Serve server, we want to manage users, server access, and repositories. Since we added our authorized key as an environment variable above, we should be able to see all the admin commands when ssh -i  git.example.com help.
Soft Serve is a self-hostable Git server for the command line.

Usage:
  ssh git.example.com [command]

Available Commands:
  help         Help about any command
  info         Show your info
  pubkey       Manage your public keys
  repo         Manage repositories
  set-username Set your username
  settings     Manage server settings
  user         Manage users

Flags:
  -h, --help   help for this command

Use "ssh git.example.com [command] --help" for more information about a command.
Users and Access
You can manage users using the user command. For example, Soft Serve creates a default admin user on the first run that uses the keys defined in SOFT_SERVE_INITIAL_ADMIN_KEYS. Let’s verify that using the info command.
$ ssh -i  git.example.com info
Username: admin
Admin: true
Public keys:
  ssh-ed25519 AAAAC3NzaC1lZDI1...
We can add more keys using the pubkey command.
ssh -i  git.example.com pubkey add ssh-rsa AAAAB3NzaC1yc2...
Use the user command to create more users. Add -a to mark user as admin.
ssh -i  git.example.com user create lemon -a
ssh -i  git.example.com user add-pubkey lemon ssh-rsa AAAAB3NzaC1yc2...
To change the current username, use the set-username command.
ssh -i  git.example.com set-username melon
Repositories
Using the repo command, you can create, delete, import, and manage repository settings. You can add/remove collaborators using repo collab. Let’s go through an example of creating a new repository, pushing code, and adding a new collaborator who can access the repo.
First, we will create a new repository.
ssh -i  git.example.com repo create hula-hoop
If you ssh into the server (without any arguments) you should see the TUI and the new repository.
Push to Repository
Now, let’s push some files to the repository.
# Clone the repository
git clone git@git.example.com:hula-hoop.git
cd hula-hoop
# Change default branch
git branch -M main
# Add content
$EDITOR README.md
git add README.md
git commit -m "Add README.md"
git push origin main
Collaborators
Let’s add the user lemon that we created earlier as a collaborator. The command add takes a repository name and a username as arguments. repo collab add REPOSITORY USERNAME.
# Add user as a collaborator
ssh -i  git.example.com repo collab add hula-hoop lemon
# List repository collaborators
ssh -i  git.example.com repo collab list hula-hoop
Nested Repositories
Soft Serve also supports nested repositories, you can create repositories with any arbitrary path. Go wild!
ssh -i  git.example.com repo create my/super/nested/new
ssh -i  git.example.com repo create my/super/nested/new/repository
Mirrors
You can also import repositories from any public remote. Use the repo import command.
ssh -i  git.example.com repo import soft-serve https://github.com/charmbracelet/soft-serve
Use --mirror or -m to mark the repository as a pull mirror.
Metadata
In Soft Serve, a repository has different properties. Repositories can be hidden, private, or mirrored. Repositories can also have their own descriptions and a project name different from the repository’s name. For example, we want the repository we imported above to be presented as Soft Serve rather than soft-serve. To do so, let’s set the repository project name.
ssh -i  git.example.com repo project-name soft-serve 'Soft Serve'
Let’s also add a description to this repository.
ssh -i  git.example.com repo description soft-serve 'The hackable self-hosted Git server!'
For more info on repository commands try repo help.
What’s Next?
That’s it for now. Check out Soft Serve’s README for more information on how to use Soft Serve.
Till next time, happy hacking!


Charm News March 2023
Bashbunni — Thu, 13 Apr 2023 00:00:00 +0000
Charm Recap: March 2023
By Bashbunni on 13 April 2023
Here we are with all the stuff that happened in March!
For the full effect, check out the video on YouTube.
For those who prefer to read instead of watch, here’s what happened…
Charm Stuff
How-To: Automated Integration Testing with VHS
We created another YouTube video all about how
you can simplify your integration testing with VHS. You can use golden files,
or even have a GIF auto-generated when a PR is created, so you can see what
changes were made to your TUI directly in the PR.
Charm Rave!!

See u in Ibiza
We hit 70k stars across our repos! To say thanks for all the love,
@meowgorithm crafted
another celebratory star mascot animation.
This time we got ~Ibiza vibes~ with a purple hue and rave lights. So thank you
both for the support and for letting us see more creative genius from
Christian.
Introducing ‘Log’
This month, we launched Log, our new
customizable logger. The goal here is to have structured logging in our
projects without needing to introduce breaking changes to our codebase. With
that goal in mind, logger was born.
What a cute lil’ bit o’ log output
It uses Lip Gloss under the hood for styling and supports multiple output
formats including text, JSON, and Logfmt. It will act as a wrapper for slog
once that new standard logger for Go is launched.
Read all about it on the blog!
Meetup, Eh?
Maas from the Charm team attended a Go Toronto
meet up and our libraries were covered by one of the speakers, Jeremy
Foran. They built a neat terminal application called “Purple Cow”.
Businesses using Charm
Cased is using Bubble Tea in their CLI!
Cased is an open source enterprise-ready tool for production work. It allows
you to handle critical issues quickly– with safe, fast access to your
servers over SSH. Reduce mistakes and improve the on-call experience.
From the Community
Gum
Snorre Magnus Davoen
made some custom zsh scripts with Gum. They were shocked at how easy it is to
add interactivity to your scripts! I mean, they’re not wrong. Gum is built to
be plug-and-play. Check out their example to see how they used it.
Bubble Tea
Post your project in our #projects channel on Discord to be featured!
fabster
SSL Checker
Hello everyone, I wanted to play with the Bubble Tea framework, so integrated
it with a very simple program of mine. I actually like the result, and I’m
using it regularly now, so made it public
Morphclue
ygo-bubble-tea
I wanted to try out a bit of Go, and I’ve decided to use the Bubble Tea
framework to start my learning process. The CLI I’ve created is a search
engine for Yu-Gi-Oh! cards. You type in the card you want to search for, a
list of results is being displayed and if you select that card you can see
pricing for different versions of that card. Nothing special, but it was a
fun little ride i’ve had with go. The code is still a bit messy and can be
probably refactored in many places. If you want to improve something,
refactor or add new features: feel free to do that. Every help is
appreciated!
waxcoin
Term ChatGPT
Hey everyone, I created an app in Go for terminal and Neovim for using ChatGPT
wkw
Repository
Discord
Recently I’ve been experiencing Bubble Tea. In order to get my hands dirty, I
started this project. Basically it is a CLI that allows you to bootstrap
projects with few clicks. More features will be added as I get more familiar
with Bubble Tea.
Kodder
Kraven: Bubble Tea Based Twitch Chat (PoC)
gzipChrist
driptionary
driptionary: A terminal client for urban dictionary
gzipChrist
drexler
I wanted to create a TUI project generator that offers a similar dev exp to
frontend tooling that I’ve used in the past, so I started hacking on drexler.
savannah
gruyère
Gruyère: A tiny (and pretty) program for viewing + killing listening ports
ssllee
GitHub Calendar Component
To start learning to build stuff with Charm, I ported over a web app I built
to a TUI. The main visual component is a ‘GitHub’ style contributions
calendar. I’m loving building it so far!
bbu
BockerR
BockerR - Backup and Restore in Docker
I’m new to Go and Charm (and I’m not really a developer either).
To learn Go I wrote a small tool that creates a PostgreSQL backups, wraps it
in a Docker image and uploads it to Docker Hub for long term storage.
This might not be the smartest thing to do, but it’s fun to implement. 😄
Using:
Bubble Tea
Lip Gloss
Log
VHS
ndsizeif
PulseManager
Control your PulseAudio devices with a colorful terminal user interface via Bubble Tea.
Wish
selkie
Chatbox
Chatbox or as I have been calling it, epic chat.
I forked someone’s project for a basic chat using wish and Lip Gloss and have
been modifying it over the past few days to render in Markdown. There are a
lot of glitches and jankiness (especially considering this is my first time
doing anything in go). I also added some dice roll commands.
Charm in the News
TechCrunch
TechCrunch featured Soft Serve in their list of fastest growing startups of 2022. Have a look at “Which Open Source Startups Rocketed in 2022?”
Rattlin’
The Rattlin’ blog posted an article to get started with
writing TUI scripts with Clojure and Gum
Linux Pratique
Gum was featured in a French Linux magazine!
New Community Videos!
There were a couple new videos featuring Glow in our Community YouTube playlist
on our channel. Check ’em out!
How to Work with Nuclei Output
Pretty Markdown Rendering in The Terminal With Glow


Commands in Bubble Tea
Bashbunni — Tue, 21 Mar 2023 00:00:00 +0000
Commands in Bubble Tea
By Bashbunni on 21 March 2023
Because of its Elm-inspired roots,
Bubble Tea has a special approach
to asynchronous operations: commands.
Commands are a fundamental part of Bubble Tea and are present whenever I/O needs
to happen. There may built-in commands you’re familiar with already such as
the tea.Quit,
tea.Tick, and
so on.
Also, if you’re just getting started with Bubble Tea we recommend checking out
the Bubble Tea Commands tutorial.
It is worth the read.
Rules of thumb
There three things to keep in mind with regard to asynchronous stuff in Bubble Tea:
Use commands for all I/O. By doing so your program will stay responsive, snappy, and maintainable. Even something as simple as reading a file from disk could cause a small lock up in your program, and commands are build to handle such cases beautifully.
Only use commands for I/O. Sometimes it’s tempting to use a command simply to send a message to another part of the program, however due to the nature of the way data flows in Bubble Tea this is never actually necessary.
Never use goroutines within a Bubble Tea program. Bubble Tea works best when you use commands and messages for communication.
The basics
Okay, so how would we write our own commands?
A Cmd is simply an alias for func() tea.Msg, so it’s just a function that
returns a message. A command could be something as simple as:
type helloMsg string

func waitASec() tea.Msg {
	time.Sleep(time.Second)
	return helloMsg("Hi, there!")
}
But how would you respond to such a command? You’d match on it in your update
method.
func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case helloMsg:
		// We caught our message like a Pokémon!
		// From here you could save the output to the model
		// to display it later in your view.
		m.greeting = msg;
	default:
		return m, nil
	}
}
Multiple commands
Sometimes you want to fire off more than one command at once. For that, use
tea.Batch.
func choresCmd() tea.Msg {
	return tea.Batch(getTheLaundry, eatDinner, petTheCats)
}
Commands with arguments
Okay, so what if you want to make a command that takes an argument? Since Cmd
is a func() tea.Msg, it can’t take an argument. So what do you do in that
case? Well, you make a function that returns a command.
func getUser(id) tea.Cmd {
	return func() tea.Msg {
		user, _ := api.GetUserByID(id)
		return gotUser{user}
	}
}
In your Update function it would look something like this:
return m, getUser(88)
Initial commands
Sometimes you’ll want to fire off a command right as your Bubble Tea program
starts without waiting for user input. For that, use Model.Init:
func (m Model) Init() tea.Msg {
	return fetchUsers
}
Or, for multiple commands:
func (m Model) Init() tea.Msg {
	return tea.Batch(
		fetchUsers,
		spinner.Tick,
	)
}
APIs calls from Bubble Tea
A lot of the time you’ll want to make API calls from Bubble Tea. Commands are
great for this.
func getUser(id int) tea.Cmd {
	return func() tea.Msg {
		res, err := http.Get(fmt.Sprintf("http://api.example.com/users?id=%d", id))
		if err != nil {
			return apiErrMsg{err}
		}
		// ...do unmarshaling and stuff...
		return fetchedUserMsg(u)
	}
}

func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyMsg:
		switch msg.String() {
		case "enter":
			// Make our API request
			return m, getUser(m.userID)
		}
	case fetchedUserMsg:
		// Here's our API response
	case apiErrMsg:
		// Oh no, an API error!
	default:
		return m, nil
	}
}
Injecting messages from outside the program
Commands work great from within a Bubble Tea program, but what if you want to send
messages to Update from outside the program? Enter
Program.Send().
It’s as simple as p.Send(someMsg{}):
p := tea.NewProgram(model)

// Later...
p.Send(someMsg{})
For details check out the
full example and
Program.Send in the docs.
Still have questions?
Let us know in Discord or in GitHub Discussions.
Learn More
Example: real time example
Discussion: injecting messages from outside the program loop


The Charm Logger
Ayman Bagabas — Tue, 21 Feb 2023 00:00:00 +0000
The Charm Logger
By Ayman Bagabas on 21 February 2023
There are many logging libraries for Go, and they all have their pros and cons.
Some are more verbose, some are more flexible, some are more performant, and
some are more opinionated. But none of them fit our needs. So we wrote our own
extensible, colorful, and easy-to-use logger.
Background
We have been reliably using the standard library’s log package. It works great
and has a simple API. However, it doesn’t have structured logging, log levels,
and is not customizable. This means that to use structured logging, we
have to introduce breaking changes to our codebase.
Another problem we were facing was excessive logging which in turn drove up our
infrastructure cost. We were logging debugging logs on our production instances.
Using leveled logging, we could set different levels per environment and avoid
logging on specific levels thus driving the cost down.
Readability was also important to us. We were looking for a library that prints
pretty logs that are easy to read in a development environment. Along with
having a simple, flexible API that accepts different types and values.
The Hunt for a Logger
There are many great logging libraries for Go. We tried switching to
logrus, apex/log, and go-kit/log before coming
up with our own logger.
Logrus was intuitive, easy to migrate to, and fully
API-compatible with the standard library logger. Given the widespread use of
logrus and the use of structured logging, this was our ideal
option. We can start the migration from the standard library logger by replacing
all the log imports with log "github.com/sirupsen/logrus". However, given
that the project is now in maintenance mode, meaning they won’t be introducing
new features, we continued our search for the most suitable logger.
We quickly stumbled upon apex/log. Apex/log has a
similar & simpler API to logrus. It was inspired by
logrus. However, it wasn’t fully API-compatible with the
standard library logger. At this point, we figured, to support structured
logging and to encourage ourselves to use structured logging, we had to
introduce breaking changes to our codebase.
For example, to make the following log example structured, we can write it in
apex/log using the log.Fields type:
// unstructured: golang "log"
log.Printf("starting app: %s, env: %s", app, env)
log.Printf("unable to process data: %s", err)

// structured & leveled: "apex/log"
log.WithFields(log.Fields{
	"app": app,
	"env": env,
}).WithError(err).Error("unable to process data")
This was not what we were looking for in terms of ease of use. We find
introducing more types and methods extraneous and slows the process of writing a
log statement. Plus, apex/log brings more dependencies given its
centralized approach. That’s when we started looking for a minimalistic library
with fewer dependencies.
Go-kit/log offers a minimal structured logging library, that simple. It offers
one extensible interface:
type Logger interface {
	Log(keyvals ...interface{}) error
}
Now, let’s write the above example with go-kit/log:
// unstructured: golang "log"
log.Printf("starting app: %s, env: %s", app, env)
log.Printf("unable to process data: %s", err)

// structured: "go-kit/log"
logger := log.NewLogfmtLogger(log.NewSyncWriter(os.Stderr))
logger = log.With(logger, "ts", log.DefaultTimestamp, "app", app, "env", env)
logger.Log("msg", "unable to process data", "err", err)
Wait, I don’t see any log levels here?
Given the extensible and minimal architecture of go-kit/log, leveled loggers
are just another wrapper around the interface. You can use the level
package to add support for
leveled logging.
// unstructured: golang "log"
log.Printf("starting app: %s, env: %s", app, env)
log.Printf("unable to process data: %s", err)

// structured & leveled: "go-kit/log"
logger := log.NewLogfmtLogger(log.NewSyncWriter(os.Stderr))
logger = level.NewFilter(logger, level.AllowInfo)
logger = log.With(logger, "ts", log.DefaultTimestamp, "app", app, "env", env)
level.Error(logger).Log("msg", "unable to process data", "err", err)
You can see this is starting to get complicated and requires some extra steps to
get it going. Unlike the standard library logger, logrus, and
apex/log, go-kit/log doesn’t offer a global logger instance to
use. Its minimal API and interface require wrapping the logger instance in
multiple layers to get the same out-of-box experience that
logrus or apex/log offer.
Shout out to all of the people behind these awesome libraries:
apex/log – A structured logger for Go.
coder/slog – A minimal structured logger.
go-kit/log – A minimalistic structured logger.
golang/glog – Leveled execution logs for Go.
hashicorp/go-hclog – A simple, structured, leveled logger.
rs/zerolog – A zero-allocation JSON logger.
sirupsen/logrus – A structured, pluggable logger for Go.
uber-go/zap – A fast, structured, leveled logger.
The Charm Logger

This is fine.
We realized that what we need is a structured, leveled, and easy-to-use logger.
It should come with a global package-wise singleton, offer multiple output
formats such as text, JSON, and Logfmt, and provide an extensible interface. We
also want it to be compatible with the standard library logger.
Just like the standard library version, the Charm logger comes with a global
singleton that can be used with the package namespace. It comes with a set of
defaults such as reporting timestamps, filtering out levels less than info, and
formatting logs for the console.
// unstructured: golang "log"
log.Printf("starting app: %s, env: %s", app, env)
log.Printf("unable to process data: %s", err)

// structured & leveled: "charmbracelet/log"
log.Error("unable to process data", "app", app, "env", env, "err" err)
Example of the output:
The Charm logger supports 3 different formats, TextFormatter (default)
suitable for console output, JSONFormatter and LogfmtFormatter for
production use. Use log.SetFormatter() or log.Options{Formatter: } option to
set the output format. TextFormatter uses Lip Gloss to style the
output. You can customize the styles by modifying the style definitions in
styles.go.
You can also create sub-loggers with log.With() and pass fields as key-value pairs.
logger := log.With("app", app, "env", env)
logger.Error("unable to process data", "err" err)
Want to send your logs to a file? No problem:
f, _ := os.OpenFile("log.txt", os.O_WRONLY|os.O_CREATE|os.O_APPEND, 0o644)
log.SetOutput(f)
log.SetFormatter(log.JSONFormatter) // Use JSON format
The logger also offers different options such as reporting caller location,
changing the log level, setting a prefix, and changing the timestamp format.
Refer to the logger
interface to see all
the available options.
That’s it! You can find Log, our
official logger, on our GitHub. If you have
any thoughts or comments, don’t be afraid to share them with us.


Do you even SSH?
Bashbunni — Thu, 02 Feb 2023 00:00:00 +0000
Do you even SSH?
By Bashbunni on 2 February 2023
This is our first video on SSH! We love the SSH protocol at Charm and are
finding more creative ways it can be leveraged for businesses. We have
libraries for SSH featured in this article, so scroll down or click on the
video to learn more!
For details, check out the video above. For those who prefer to read rather
than watch, see the transcript below.
Let’s Get Into It
Most of you have probably seen SSH either used at work, or to clone GitHub
repos, but maybe you aren’t quite sure how it works or you’re curious to
know why we think it’s so cool. This one’s for you.
Don’t forget to like and subscribe if you enjoy SSH and terminal-related
content!
Now let’s talk about SSH. SSH is the go-to for authorizing access to remote
servers and services. You authenticate with an SSH private key that has an
authorized public key on the server.
SSH Binary vs SSH Protocol
First off, let’s preface this by stating that SSH != OpenSSH. OpenSSH, AKA
the ssh binary, is “a suite of secure networking utilities based on the
Secure Shell (SSH) protocol, which provides a secure channel over an
unsecured network in a client–server architecture“. Interestingly, OpenSSH
actually started out as a fork of SSH, but has since become proprietary
software, according to Wikipedia. OpenSSH specializes in tools for remote
systems administration, while SSH is a flexible protocol with an open
architecture that makes it suitable to various use-cases.
You probably see SSH commonly used for:
Administrating a server remotely (with OpenSSH)
Authorizing remote processes, SCP for example, which allows you to send files via an SSH tunnel so the data is encrypted in transit.
Providing secure access for users
Securely mounting a directory on a remote server as a file system
Port forwarding
And less commonly used for:
Browsing the web through an encrypted proxy connection with SSH clients (extra nerd points for that)
But there are plenty more.
SSH Layers
Now, before we jump into Charm stuff, we need to break down the layers of SSH.
The Layers:
The transport layer
The user authentication layer
The connection layer
The transport layer uses the TCP port to handle initial key exchange as
well as server authentication, and set up encryption, compression, and
integrity verification. It exposes to the upper layer an interface for
sending and receiving plaintext packets.
The user authentication layer is responsible for client authentication,.
Because authentication for SSH is client-driven, you may get asked for your
key password by the client while the server responds to authentication
requests. The most common authentication method I’ve seen is public-key
authentication, though there are other methods of authentication supported
by SSH.
The connection layer handles different channels in your SSH connections.
You might have multiple channels per connection as they work to transfer
data bi-directionally. Some examples of channels include:
Shell for terminal shells, SFTP and exec requests (including SCP transfers)
Direct-TCPIP for client-to-server forwarded connections
Forwarded-TCPIP for server-to-client forwarded connections
Charm × SSH
Now, let’s talk about how we use SSH at Charm. First off, we don’t touch
OpenSSH on our servers, so you are not being given shell access, period. We
serve a TCP connection using the SSH protocol, and you (the app developer)
can do whatever you want with it. It’s pretty much like reading from STDIN and
writing to STDOUT/STDERR. With Wish, you can define what kind of authentication
you might want for your SSH apps, and you can define what users are authorized
to interact with the application, etc.
Now, we are also using SSH for identity management with Charm Cloud. How this
works is the first time you run charm it creates an SSH key-pair for you.
From then on, it uses those keys to verify your identify so you can access the
hosted file system, encryption and decryption functions, and your key-value
stores.
If you’re ever worried you might lose your SSH keys, fear no more: we have
Melt, which allows you to back up and
recover your SSH key-pairs with seed phrases so you can keep a hard copy in a
safe place.
Learn more about our SSH tools:
Wish
Wishlist
Melt
Charm Cloud
You can check out our Soft Serve TUI
TUI over ssh by running ssh git.charm.sh from your terminal for an
interactive demo.
Ciao!


What a year!
Charm — Wed, 21 Dec 2022 00:00:00 +0000
What a year!
Charm’s 2022 highlights
By Charm on 21 December 2022
Charm’s mission is to make the command line a glamorous platform for creative,
industrial-grade computing.
Given that, we continuously strive for clarity and open communication. We’re
excited to share more with our community via this blog, including the recent
posts featuring the nuances of SSH key marshaling and
the new VHS publish feature. We also want to
keep you all up to date with broader Charm learnings as 2022 has truly been
transformative.
In spirit of open source, we’re proud to highlight some milestones achieved:
Star power
In April the team was celebrating crossing 30,000 GitHub stars, a marker in the
open source world! We even open sourced the
3D model
that was made in celebration. Yet when Gum and VHS launched,
they each hit the global GitHub top 3 within days. These events, coupled with
strong growth of our existing products, pushed us past 65,000 GitHub stars in
record fashion.
Developer love
Bubble Tea, our TUI framework, crossed 10,000 stars early in
the year. Shortly thereafter, we saw organizational adoption and use cases for
Bubble Tea apps emerge. From Microsoft’s Aztify, a tool to bring
Azure resources under Terraform management, to
AWS’s EC2 Spot Interruptor, a tool that triggers EC2 spot interruption
notifications and rebalance recommendations, to
Doctl, Digital Ocean’s
official CLI, and most recently Cockroach-Gen from CockroachDB. It’s
inspiring to see that developer love for Bubble Tea has grown to the point
that developers are actively integrating it into their organizations! There
have now been 1,750 Bubble Tea apps built to date: that’s 3.5x more than that
of last year. And Glow, our markdown reader, continues to be shared
with the wider community with over 31,000 users, almost doubling that of the
past two years.
Connecting with community
As an open source startup, the community truly drives what we do. This year,
we prioritized expanding communication channels with our developer users.
In addition to Twitter, Slack, Mastodon, we launched Instagram, YouTube,
Discord for more conversational, produced, and streamlined content. On
YouTube alone, we’ve published 29 videos, racking over 66,000 views and
2,450 subscribers! Recently, we even met our community in person
via a co-hosted Microsoft event!
This year, we’re grateful to have been featured by Microsoft,
GitHub, Twitter, Supabase,
Changelog, etc. When one searches for “command line” on Hacker
news, Charm tops the charts.
2022 has been transformative. Thank you for your support!


Marshaling SSH Private Keys
Carlos Becker — Mon, 19 Dec 2022 00:00:00 +0000
Marshaling SSH Private Keys
By Carlos Becker on 19 December 2022
Not long ago, when I was building melt, I learned something
interesting: if you restore a private key from its seed, and marshal it back to
the OpenSSH Private Key format, you’ll always get a different block in the
middle.
Why?
That lead to an investigation of how the private key format works. I didn’t
find many good references out there, except OpenSSH’s source code.
Let’s start from there, shall we?
We can see in the function sshkey_private_to_blob2
in sshkey.c,
there’s this interesting piece of code:
/* Random check bytes */
check = arc4random();
if ((r = sshbuf_put_u32(encrypted, check)) != 0 ||
    (r = sshbuf_put_u32(encrypted, check)) != 0)
	goto out;
We see there that it creates what seems to be a random uint32, and then calls
sshbuf_put_u32 two times, adding it to encrypted and expecting it all to
succeed.
Interesting… why?
The best clue after that lies in the
PROTOCOL.key
file:
	uint32	checkint
	uint32	checkint
	byte[]	privatekey1
	string	comment1
checkint… same name… the answer must be here, right?
Going further:
Before the key is encrypted, a random integer is assigned to both checkint
fields so successful decryption can be quickly checked by verifying that both
checkint fields hold the same value.
Aha! So that’s why it’s always different! The checkints are used to check
that decryption succeeded. When decrypting the key, we don’t know their value,
just that they should be equal.
Cool!
What about Go?
When we started this story, I mentioned I was working on melt, which is
written in Go. So far, we’ve looked in to C code, but what about Go?
Turns out there’s an
unresolved merge request
adding SSH key marshaling into Go’s crypto/ssh package.
We can find the same checks there (called Check1 and Check2) but the
code might be a bit easier to read:
// Random check bytes.
var check uint32
if err := binary.Read(rand.Reader, binary.BigEndian, &check); err != nil {
	return nil, err
}
pk1.Check1 = check
pk1.Check2 = check
P.S. If you want to use this in your Go program, I’m keeping a
repository with these changes.
Playground
We learned that the Private Key file, in the OpenSSH format, will always be
a bit different, even if it’s generated with the same parameters. But… is it
still the same key? What happens now?
We can verify that using melt!
Let’s create a new key to play with. You can do so with:
ssh-keygen -t ed25519 -f post
And then run melt to get a mnemonic:
melt ./post >seed
For what its worth, here is the mnemonic for the key I created:
obey axis lecture satoshi deal comic first unfold bomb control attitude lawsuit
this brown often fault myself rabbit assume miss modify riot around punch
Now, let’s restore it a couple of times:
melt restore ./post1 <seed
melt restore ./post2 <seed
Now, let’s check a couple of things, starting with the check sum of the private
keys:
sha256sum post post1 post2
a9a08d6ae71412e0397e1c76d9300002d0cb69e484823dd684d217ee07f32081  post
ec7f45126a4bf96a913b66079c1e1773ca809c6b4a653885a1c49e08d2b4d978  post1
cab1849c9560b6705a335192bcb3991ae2ba8ac479d51659e2325aeeb3ab2476  post2
All different…which is expected, due to the checkint we just learned about.
Let’s now check the public keys:
sha256sum post*.pub
562de9510ca7278f3284f9f0114e8dc757b557c92f0b1744514c42eb9c1b0d81  post.pub
8dd282d6ad5a0fa6da2a2054b70ac96c257a58ef4c23715f02b9885329094a27  post1.pub
8dd282d6ad5a0fa6da2a2054b70ac96c257a58ef4c23715f02b9885329094a27  post2.pub
Except for the first one, they are all equal. So what’s the difference between
them?
diff -u post.pub post1.pub
--- post.pub    2022-12-07 13:28:36.009649296 -0300
+++ post1.pub   2022-12-07 13:31:34.426816707 -0300
@@ -1 +1 @@
-ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPA8QtyAE1DLpUIY3otmLILZv9XdRlXv37hHEWTGib7p carlos@darkstar
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPA8QtyAE1DLpUIY3otmLILZv9XdRlXv37hHEWTGib7p
Ah, our original key had a memo, and the restored ones don’t. Not a big deal!
What about the private keys’ fingerprints?
ssh-keygen -l -f post > post.finger
ssh-keygen -l -f post1 > post1.finger
ssh-keygen -l -f post2 > post2.finger
cat post*.finger
256 SHA256:KfCFwx1/vfcV/XQqdneOMOdgpbVu4Nxz32buks4MLpI carlos@darkstar (ED25519)
256 SHA256:KfCFwx1/vfcV/XQqdneOMOdgpbVu4Nxz32buks4MLpI post1.pub (ED25519)
256 SHA256:KfCFwx1/vfcV/XQqdneOMOdgpbVu4Nxz32buks4MLpI post2.pub (ED25519)
Again, the same key. The only difference is the memo.
Now let’s check how different the private keys really are:
diff -u post1 post2
--- post1       2022-12-07 13:31:34.426816707 -0300
+++ post2       2022-12-07 13:31:37.870839247 -0300
@@ -1,7 +1,7 @@
 -----BEGIN OPENSSH PRIVATE KEY-----
 b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtz
 c2gtZWQyNTUxOQAAACDwPELcgBNQy6VCGN6LZiyC2b/V3UZV79+4RxFkxom+6QAA
-AIjRy3cc0ct3HAAAAAtzc2gtZWQyNTUxOQAAACDwPELcgBNQy6VCGN6LZiyC2b/V
+AIhYJw2fWCcNnwAAAAtzc2gtZWQyNTUxOQAAACDwPELcgBNQy6VCGN6LZiyC2b/V
 3UZV79+4RxFkxom+6QAAAECX4h38X7OCXJXfaRkl7Dq/Hgw6JmqfklYEN8bo63RD
 DfA8QtyAE1DLpUIY3otmLILZv9XdRlXv37hHEWTGib7pAAAAAAECAwQF
 -----END OPENSSH PRIVATE KEY-----
Just one line–about 12 chars–are different: jRy3cc0ct3HA vs hYJw2fWCcNnw.
All that said, for all intents and purposes it’s the same key, which shouldn’t
be a surprise, but it’s good to know anyways!
Hope you enjoyed this trip into how OpenSSH private keys are marshaled, and
I’ll see you in the next one!


VHS GIF Hosting!
Maas Lalani — Mon, 19 Dec 2022 00:00:00 +0000
Host Your GIFs with VHS
By Maas Lalani on 19 December 2022
VHS now ships with automatic GIF hosting making it easy to share your
VHS creations with your friends, foes, coworkers, and the internet. To publish
your GIFs just add the --publish flag.
vhs --publish demo.tape
But first things first.
VHS? What’s that?
In case you missed it, VHS is a tool that generates GIFs and videos of
terminal GIFs from code. To generate a GIF with VHS, you write a simple
.tape file, which instructs VHS how to interact with the terminal, and pass
it into the vhs binary.
Here’s what a .tape file could look like:
# Where should we write the GIF?
Output demo.gif

# Set up a 1200x600 terminal with 46px font.
Set FontSize 46
Set Width 1200
Set Height 600

# Type a command in the terminal.
Type "echo 'Welcome to VHS!'"

# Pause for dramatic effect...
Sleep 500ms

# Run the command by pressing enter.
Enter

# Admire the output for a bit.
Sleep 5s
Once you have written your .tape file, just pass it to VHS:
vhs < demo.tape
Voilà! VHS will output a shiny terminal GIF entirely generated from the
code you wrote!
Publishing GIFs
We wanted to make sharing terminal GIFs with VHS as easy as creating them, so
we’re pleased to introduce vhs --publish.
When you add the --publish flag, VHS will host your GIF on vhs.charm.sh and
provide you with a URL that you can share with your fellow command-line
dwellers.
So this…
vhs --publish demo.tape
Will output this…
…which will then be available at a URL like https://vhs.charm.sh/vhs-6bx5XJGgNmJLVmvicnXJ9i.gif.
And if you forgot to pass the --publish flag while creating your GIF, worry
not. You can use vhs publish to host the GIF even after it’s already been
generated:
vhs publish demo.gif
Bonus: Home Video Recording
Want to play around with vhs --publish right now but don’t have any .tape
files laying around? Say hello to vhs record.
vhs record, a relatively new feature, will record your terminal activity and
write the output into a tape file, almost like magic.
vhs record > file.tape
# perform actions, do stuff...
vhs file.tape --publish
We hope that VHS makes it easy for you
to record and share your terminal applications with others. We love seeing
your terminal GIFs and you’re always welcome to share them with us.
And, as always, let us know if you have any feedback.