Beam

Beam me up Ferris!

What is Beam?

Beam an interface on top of the Teleport CLI. It uses skim, a fuzzy finder written in Rust, to provide a nice interface for searching and filtering.

Table of Contents

• Beam
  • What is Beam?
  • Table of Contents
  • Installation
  • Configuration
    • Caching
  • Usage
    • Search Syntax
  • Adding completions to your shell

Installation

Make sure that you have the Teleport CLI installed, before using Beam.

For installing you will have to install Rust. Rustup is the recommended way to do that.
You can install beam through running:

rustup default nightly && rustup update

cargo install beamcli

Configuration

Before using Beam you will have to configure a default profile.

$ beam configure
✔ Profile name · myProfile
✔ Do you want to auto-select this profile, using a regex pattern on the hostname? · no
✔ Proxy · teleport.example.com
✔ Username · dzefo
✔ Authentication Method · default
✔ Cache TTL · 86400
✔ Do you want to only show specific labels? · no

If you want to use SSO as your authentication method, you will have to set sso for Authentication Method

For only showing specific labels, you can set yes for Do you want to only show specific labels?

$ beam configure
...
✔ Do you want to only show specific labels? · yes
✔ Label · env
✔ Add another label? · yes
✔ Label · application
✔ Add another label? · no

Pattern matching

If you want to select a specific profile, for a set of hostnames, that match a specific pattern, you can specify yes for Do you want to auto-select this profile, using a regex pattern on the hostname?

$ beam configure
Configuring profile dev-profile:
✔ Do you want to auto-select this profile, using a regex pattern on the hostname? · yes
✔ Regex Pattern for auto-selecting profile · \b(quality|staging)\b.*
...

Beam will then match any of the following hostnames:

• quality.app.example.com
• staging.app.example.com

If the hostname doesnt match any profile pattern, Beam will use the default profile.

Important: Beam will only use the proxy from the default profile, when running the beam command, as it does not know the hostname, before selecting it. When using the beam connect <hostname> command, Beam will use the hostname from the command line and is able to use the proxy from the profile.

Caching

By default Beam caches the list of nodes it receives from Teleport for 24 hours. To avoid using cache you can use the --clear-cache or -c flag:

$ beam -c

You can change the cache duration using the --cache-ttl flag. The following example will cache the list of nodes for 1 hour:

$ beam config set --cache-ttl 3600

Usage

A few useful Beam commands:

1. Opening a fuzzy finder view for selecting a host:

$ beam

2. Listing the names of all available nodes

$ beam list --format names
host1.example.com
host2.example.com

3. Directly connect to a host via its hostname

$ beam connect server.example.com

4. Manually selecting a profile to use

$ beam --profile myProfile

Search Syntax

Beam uses skim under the hood for its fuzzy search. The syntax for searching is the same as for skim. See skim for more information.

skim also supports the combination of tokens.

• Whitespace has the meaning of AND. With the term src main, skim will search for items that match both src and main.
• | means OR (note the spaces around |). With the term .md$ | .markdown$, skim will search for items ends with either .md or .markdown.
• OR has higher precedence. So readme .md$ | .markdown$ is grouped into readme AND (.md$ OR .markdown$).

Adding completions to your shell

In order to add completions to your shell, you can use one of the following commands:

$ beam completions zsh > ~/.zfunc/_beam

$ sudo apt install bash-completions
$ mkdir -p ~/.local/share/bash-completion/completions
$ beam completions bash > ~/.local/share/bash-completion/completions/beam

$ mkdir -p ~/.config/fish/completions
$ beam completions fish > ~/.config/fish/completions/beam.fish