Topia Tools CLI

A command-line interface tool for Topia project development.

Quick Start (NPX - Recommended)

The fastest way to create a new Topia project is using NPX:

npx @rtsdk/topia-tools create my-topia-project

This command will:

1. Create a new directory with your project name
2. Set up a complete TypeScript project structure
3. Install @rtsdk/topia-tools as a dependency
4. Create all necessary configuration files
5. Guide you through the initial setup

After creation, navigate to your project and get started:

cd my-topia-project
npm run topia init    # Configure your Topia API key
npm run topia import  # Import an existing Topia project
npm run dev           # Start development server

Installation (Alternative Methods)

You can install this CLI tool in another repository using one of the following methods:

Method 1: Install from npm (if published)

npm install -g topia-tools

Method 2: Install locally using yalc

1. In the topia-tools directory, build and publish locally:

npm run local-publish

This will compile the TypeScript code, make the dist/index.js file executable, and publish the package to the local yalc store.

2. In your target repository, install the package:

npx yalc add topia-tools
npm install

3. Link the binaries (this step is crucial):

npm link

If you encounter "command not found" errors, try one of these solutions:

• Install the package globally in the target repository:

npm install -g ./node_modules/topia-tools

• Create symbolic links manually:

sudo ln -s $(pwd)/node_modules/topia-tools/dist/index.js /usr/local/bin/topia
sudo ln -s $(pwd)/node_modules/topia-tools/dist/index.js /usr/local/bin/topia-tools

Method 3: Install directly from GitHub

npm install -g github:username/repo#branch

Usage

Once installed, you can use the CLI tool with either the topia or topia-tools command:

topia --help
# or
topia-tools --help

This will display all available commands:

Usage: topia-tools [options] [command]

CLI tool for Topia project development

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  create [project-name]  Create a new Topia project
  init                   Initialize a new Topia development environment
  import                 Import a project from Topia
  sync                   Sync local changes with the Topia server
  dev                    Start a development server
  help [command]         display help for command

Getting Started

1. Initialize the development environment:

topia init

This will prompt you for your Topia API keys and set up the necessary folder structure.

2. Import a project:

topia import

This will fetch available projects from Topia and let you select one to import.

3. Start the development server:

topia dev

This will start a local development server for your project.

4. Sync changes:

topia sync

This will sync your local changes with the Topia server.

Requirements

• Node.js 20.10.0 or higher
• npm 10.2.3 or higher

Dependencies

This CLI tool includes several runtime dependencies:

• TypeScript: Used for compiling scripts on-the-fly
• dotenv: Used for loading environment variables from a .env file
• axios: Used for making HTTP requests to the Topia API

When you install the package, these and other required dependencies will be automatically installed.