TTY Toolkit

Commands generated by teletype consist of a class that inherits from App::Command. The core logic must be implemented within the execute method.

Accessing Helpers

App::Command provides helper methods that lazy-load tty components. You can access these within your execute method:

• prompt(**options): Returns a TTY::Prompt instance for user input.
• command(**options): Returns a TTY::Command instance for running external shell commands.

Note: All tty components are added to your app.gemspec by default, but you can modify this to include only what you need.

Use the teletype new [app-name] command to bootstrap a complete command-line application project structure. This setup is based on the Bundler gem command but enhanced with directories for command development.

Available Flags

• --author, -a: Injects a name into the generated documentation.
• --ext: Creates a binary executable in exe/GEM_NAME and includes it in the .gemspec. Disabled by default.
• --license, -l: Sets the open source license. Supported values: agplv3, apache, bsd2, bsd3, gplv2, gplv3, lgplv3, mit, mplv2, custom. Defaults to mit.
• --test, -t: Configures the testing framework. Supported values: rspec (default) and minitest.

Use the teletype executable to scaffold a new command-line application. This provides the initial project structure following Unix-style patterns.

To create a new application named app, run:

$ teletype new app

You can install the entire TTY toolkit or individual components via RubyGems.

To install all components, add gem 'tty' to your Gemfile and run bundle. Alternatively, you can install the toolkit directly via the command line.

To install only specific components, use the gem 'tty-*' pattern in your Gemfile.

Once you have scaffolded an application, you can expand its functionality by adding new commands. Navigate into your application's directory and use the add command.

To add a command named config to your application, run:

$ cd app
$ teletype add config

The TTY::Gemspec class provides utilities for reading, writing, and formatting Ruby .gemspec files. It is designed to handle the extraction of the gemspec variable name and its indentation levels to ensure that newly added dependencies match the existing file's style.

Key Capabilities:

• Reading: Loads gemspec content and automatically detects the variable name (e.g., spec or gem) and its indentation.
• Writing: Persists the current content back to a file.
• Formatting: Generates formatted dependency strings that respect the existing indentation and variable naming conventions.

To define a flag that is available to every command and subcommand in your application, use class_option within your CLI class. These options are also merged into the options hash available to individual command instances.

module App
  class CLI < Thor
    class_option :debug, type: :boolean, default: false, desc: 'Run in debug mode'

    # ... commands ...
  end
end

Teletype uses Thor for command-line parsing. You define how commands appear in help menus using desc and long_desc in your CLI class (usually lib/app/cli.rb).

Argument Syntax

• desc 'command NAME': Shows a required argument.
• desc 'command [NAME]': Shows an optional argument.
• desc 'command NAME...': Shows a variadic argument.

Long Descriptions

Use long_desc to provide detailed usage instructions, which are displayed when a user runs app [command] --help.

module App
  class CLI < Thor
    desc 'config [FILE]', 'Set and get configuration options'
    long_desc <<-DESC
      You can query/set/replace/unset options with this command.
      The name is an optional key separated by a dot.
    DESC
    def config(file = nil)
      # ...
    end
  end
end

Use method_option (or method_options for multiple) to define flags and options for a specific command. Options are accessed via the options hash inside the command's execute method.

Supported Metadata

• :aliases: Array of short flags (e.g., ['-e']).
• :banner: Description of the value (e.g., `

Once a project is initialized, use teletype add [command-name] to generate new command files and templates. Command names should use camelCase or snake_case (e.g., add_config_command).

Command Flags

• --args: Defines positional arguments. Use space-delimited names.
  • Required: name
  • Optional: "name = nil" (enclosed in quotes)
  • Variadic: *names
• --desc: Provides a custom description for the command.
• --force: Overwrites an existing command implementation.

Subcommands

To create a subcommand, provide both the parent command and the subcommand name: teletype add [parent] [subcommand].