houston-cli

Houston CLI

Houston CLI is a command-line tool to scaffold and maintain Vue component prototypes for the UXE Studio project. It streamlines the process of creating and managing Vue component prototypes in a structured way, whether you're working on the real project or in a safe "testing" sandbox.

Table of Contents

• Installation
• Environment Setup
• Quick Start
• Commands
  • launch
  • github
  • testing-mode
  • find
  • webify
  • clean
• Folder Structure & Paths
• Testing
• Uninstallation
• Contributing

Installation

git clone git@github.com:dialpad/houston-cli.git
cd houston-cli
npm install
chmod +x bin/houston.js
npm install -g .

You’ll now have a global houston command.

Environment Setup

For the webify command to work, you need to set up your Figma token:

1. Copy the environment template:

   cp .env.example .env
   

2. Get your Figma token:

   • Go to Figma Settings > Personal Access Tokens
   • Generate a new token
   • Copy the token

3. Add your token to .env:

   FIGMA_TOKEN=your_actual_figma_token_here
   

⚠️ Important: Never commit your .env file with real tokens to version control!

Quick Start

Create a New Prototype

From the root of your UXE Studio project (or when testing, from the repo root with testing-mode enabled), run:

# Start the interactive prototype creator
houston launch

# Follow the prompts to:
# 1. Enter component name in PascalCase (e.g., "MyButton")
# 2. Add project details (name, status, description)
# 3. Choose a template (empty, web, meetings, reference)

# Your new component will be created in:
# - prototypes/MyButton.vue
# - prototypes/MyButton.meta.js

Add Components to a Prototype

# Add Dialtone components to an existing prototype
houston add

# Follow prompts to:
# 1. Select the target prototype
# 2. Choose components from the Dialtone library
# 3. Components will be added with proper imports and usage examples

Example Workflow

# 1. Create a new prototype
houston launch
# > Enter component name: MyAwesomeFeature
# > Select template: web

# 2. Add it to version control
cd path/to/your/project
houston github
# Follow prompts to create a branch and push changes

# 3. Add components to your prototype
houston add
# Select components to add (e.g., Button, Input, etc.)

Commands

launch

houston launch

Starts an interactive session to create a new Vue component prototype. The command will:

1. Ask for the component name in PascalCase (e.g., MyComponent)
2. Request project details (name, status, description, etc.)
3. Generate:
   • A .vue component in the prototypes directory
   • A .meta.js file with component metadata
   • Update the components registry

github

houston github

Helps you set up your Git workflow by:

1. Checking your current branch
2. Creating a new branch if you're on master
3. Committing any uncommitted changes
4. Pushing to the remote repository

Example flow:

$ houston github
🚀 Setting up your Git workflow

✓ Currently on branch: master

Would you like to create a new branch? (Current: master) › (Y/n)
Enter new branch name (e.g., feature/my-feature): feature/new-button
✓ Switched to new branch: feature/new-button
✓ Created initial commit

Pushing to GitHub...
✓ Pushed to origin/feature/new-button

✓ Done!

Steps completed:
1. Created new branch
2. Switched from master to new branch
3. Created initial commit
4. Pushed new branch to GitHub

Now you can start coding!

testing-mode

Enable or disable a sandbox under ./testing/src/... so you can safely try out Houston without touching your real UXE Studio files.

• Enable:

  node bin/houston.js testing-mode on
  # or, if globally installed:
  houston testing-mode on
  

• Disable:

  node bin/houston.js testing-mode off
  # removes `testing/` and the .houston-log
  

Once enabled, all generate/read/write commands will operate under testing/src/....

find

Search for an existing .vue file and open it in your editor.

houston find <term>      # Search for prototypes

• Scans the corresponding prototypes folder for filenames matching <term> (case-insensitive).
• Presents an interactive list.
• Opens the selected file in your IDE or default editor.

webify

Fetch Figma component properties and generate code connect files.

houston webify <componentName> --figma <figmaUrl>

• Fetches component data from the Figma API using the provided component URL
• Generates a .json file with the component's metadata
• Creates a .js file with Figma Code Connect configuration
• Requires FIGMA_TOKEN environment variable (see Environment Setup)

Example:

houston webify Button --figma "https://www.figma.com/design/abc123/Component?node-id=1-23"

This will create Button.json and Button.js files with the component's properties and code connect setup.

Note: Make sure you have set up your FIGMA_TOKEN in your .env file before using this command.

clean

houston clean

Reverts all changes logged by Houston, including:

• Created prototype files (.vue, .meta.js)
• Component registry updates
• Generated thumbnails
• Testing mode files

Note: This action cannot be undone. Make sure to commit or back up any important changes first.

Folder Structure & Paths

• Templates (never changes):

  src/
    templates/
      prototypes/
  

• Generated output (real vs. testing):

  [PROJECT_ROOT]/
    src/
      prototypes/    ← .vue + .meta.js + state.js
      data/
        components.js  ← updated by addElement
        dialtone-components.json
    public/
      components/    # Thumbnails
        light/
        dark/
  

In testing mode, prototypes go to testing/prototypes/ instead of prototypes/.

Testing

To manually test any command from the repo root:

# 1) Enable sandbox
node bin/houston.js testing-mode on

# 2) Run commands
node bin/houston.js launch
node bin/houston.js find -p MyProto
node bin/houston.js clean

# 3) Disable sandbox
node bin/houston.js testing-mode off

All files—including dialtone-components.json, .meta.js, .vue, state files, images, and .houston-log—will be created under testing/ and then removed on disable.

Uninstallation

npm uninstall -g houston-cli

Contributing

We welcome contributions to Houston CLI! Here's how to get started:

1. Fork & Clone the repository
2. Create a Feature Branch

   git checkout -b feature/your-feature-name
   

3. Set Up Development Environment

   npm install
   npm link  # Creates a global symlink for local development
   

4. Make Your Changes
   • Follow the existing code style
   • Add tests for new features
   • Update documentation as needed
5. Test Your Changes

   # Run tests
   npm test
   
   # Test in a sandbox
   houston testing-mode on
   # Test your changes
   houston testing-mode off
   

6. Submit a Pull Request
   • Ensure all tests pass
   • Update the README if needed
   • Reference any related issues

Code Style

• Use ES6+ JavaScript
• Follow existing code style (2-space indentation, single quotes)
• Keep functions focused and modular
• Add JSDoc comments for public functions

Testing

• Add unit tests for new features
• Test edge cases
• Ensure existing tests pass

Happy Prototyping!
Questions or feedback? Reach out to the UXE team.