CLI Reference

Getting Started: teclada setup

This command should typically be used when configuring Teclada on a machine for the first time. It performs all steps needed to configure Teclada, and is equivalent to running separate teclada commands in the following order:

• teclada validate
• teclada configure
• teclada enable
• teclada start
• teclada init_bash

Accepts any flag accepted by those commands.

Connection commands

Provisioning the host: teclada configure

This command connects to the Teclada service and provisions the current machine. It requires either a username & password, or a one-time key generated in the browser. If this completes successfully, a certificate will be issued to this machine. The teclada daemon will use that machine in the future when communicating with the Teclada service.

Flags:

Auth options: If no auth options are passed, the user will be prompted for input. --token and --email conflict with each other. If --email is passed without --pass, the user will be prompted for the password. For a non-interactive installation, use --token or --user + --pass.

• --token: The one-time key to use when provisioning this machine. Conflicts with --email.
• --email: The email of the user to authenticate as when provisioning this machine.
• --pass: The password of the user to authenticate as when provisioning this machine.
• --authmode: The installation authentication mode to use. Options are [e]mailpass or [t]oken. Ignored if --email or --token is specified directly.

Other options:

• --name: The name that should be assigned to this machine. If not specified, the user will be prompted. If using a one-time key, this flag is only used for multi-instance machines. Passing this flag is important when configuring an instance of a multi-instance host, in order to distinguish the instance.
• --logo: boolean, default true. If false, do not print TECLADA in ASCII art. This is implied by the general flat --quiet.

Developer Options: You probably don't want to use these.

• registration_server: The address of the Teclada service that will register this machine and issue its certificate. Defaults to backend.teclada.com.
• registration_identities: Certificate identities to trust for the registration server. Defaults to backend.teclada.com.

If running as root, the configuration and keys are stored by default in /etc/teclada. If running as a user, the configuration and keys are stored by default in ~/.teclada.

Checking configuration: teclada is_configured

This command is intended for use in scripts. It returns 0 if Teclada is configured (teclada configure has been run). It returns 1 otherwise.

Service management

These commands manage running Teclada with systemd (Linux) or Launchd (Mac).

Staring on boot: teclada enable

This configures Teclada to run on boot, using either systemd (Linux) or launchd (Mac).

This operation only functions if teclada is installed as root.

Not starting on boot: teclada disable

This operation will undo a teclada enable and prevent Teclada from starting on boot.

This operation only functions if teclada is installed as root.

Start Immediately: teclada start

This starts Teclada, regardless of whether it's configured to start automatically on boot.

If Teclada is already running, this command has no effect. The running instance is not restarted. Use teclada restart for that.

This operation only functions if teclada is installed as root.

Don't confuse start with run, which runs the Teclada daemon directly rather than asking systemd/launchd to do it.

Stop Immediately: teclada stop

This starts Teclada, regardless of whether it's configured to start automatically on boot.

This operation only functions if teclada is installed as root.

Restart Immediately: teclada restart

Restarts a running Teclada instance.

Status: teclada status

Displays status information for the Teclada systemd daemon. Not yet implemented for launchd on Mac.

Running Directly

When installing Teclada on a normal computer, these commands are typically unnecessary - use the Service-based commands above. However, these are useful for ephemeral machines (e.g. Kubernetes pods, Docker images, etc.)

Status: teclada run

Runs the Teclada daemon in the foreground, as a normal process.

This command is useful for ephemeral locations, like Kubernetes pods or Docker instances.

For backwards compatibility, running teclada with no positional arguments is an alias for teclada run.

Flags:

• --noreboot: By default, Teclada will try to reboot itself if it crashes. this prevents that.
• --config_path=<path>: Path to the .pbtxt file generated by configure. Defines the identity the host runs as, along with other information.

Status: teclada oneshot

A combination of the following commands:

• teclada configure
• teclada run

This accepts a token or user+pass, and then starts Teclada directly with the credentials provided.

Flags

Accepts all flags that are accepted by configure or run.

Status: teclada bg_run

Runs Teclada directly as a background process.

Allows another process to be specified as well, which is run afterward in the foreground. If done, Teclada will exit when that foreground process exits. Here's an example:

teclada bg_run -- /my/process

Teclada will be run in the background, and will exit when /my/process exits.

Flags

Accepts all flags that run accepts.

Status: teclada bg_oneshot

A combination of the following commands:

• teclada configure
• teclada bg_run

Behaves just like oneshot but runs Teclada in the background like bg_run.

Flags

Accepts all flags that are accepted by configure or run.

Miscellaneous

Setting up Bash: teclada update

Request that Teclada update itself.

If the update fails, try teclada update --update=LOCAL to use a backup builtin updater.

Setting up Bash: teclada init_bash

Teclada only works with Bash, but many systems now default to zsh. This can cause a terrible experience for new users, as many environment variables (including $PATH) won't be set up. Teclada offers the init_bash subcommand as a tool to ease the transition back to Bash.

init_bash reads the current user's environment variables and copies them to the file ~/.teclada_backup_vars. It then adds a code block to ~/.bash_profile to source ~/.teclada_backup_vars.

If running setup as root, this subcommand walks up the process tree to find the first non-root user, and performs this operation for that user.

The following variables are not copied:

"TERM_SESSION_ID",
"SSH_AUTH_SOCK",
"LC_TERMINAL_VERSION",
"ITERM_PROFILE",
"LANG",
"PWD",
"SHELL",
"__CFBundleIdentifier",
"TERM_PROGRAM_VERSION",
"TERM_PROGRAM",
"PATH",
"LC_TERMINAL",
"COLORTERM",
"TERM",
"HOME",
"TMPDIR",
"USER",
"LOGNAME",
"ITERM_SESSION_ID",
"SHLVL",
"OLDPWD",
"_"

This should not be relied upon long-term. It is intended only as a transitional tool. Users should configure their Bash environment properly and remove ~/.teclada_backup_vars when possible.

Validating the installation: teclada validate

This command ensures Teclada can run on the current machine. In particular, it ensures that:

• shared library dependencies are present
• bash is present
• bash is new enough to run Teclada

More validations may be added in the future.

Global Flags

teclada accepts a number of flags for all subcommands.

• --user: Normally, all 'service' configuration commands and the setup command will automatically elevate to root. Setting --user=true will prevent that.
• --quiet: Prevents normal output. Does not prevent error output. Anything that would require prompting the user via stdin will fail. Specify values via flags instead.
• --silence: Fully silence both stdout and stderr. Implies --quiet.
• --log=<file>: Write detailed logs to the specified file.
• --logtostderr: Write detailed logs to stderr.
• --max_log_size=<size>: The maximum size-on-disk of the log file specified with --log. Use a number plus a size suffix, such as 8m or 64k.