CLI infrastructure for Travetto framework
npm install @travetto/cliInstall: @travetto/cli
``bash
npm install @travetto/cli
yarn add @travetto/cli
`
The cli module represents the primary entry point for execution within the framework. One of the main goals for this module is extensibility, as adding new entry points is meant to be trivial. The framework leverages this module for exposing all executable tools and entry points. To see a high level listing of all supported commands, invoke trv --help
Terminal: General Usage
`bash
$ trv --help
Usage: [options] [command]
Commands:
doc Command line support for generating module docs.
doc:angular Generate documentation into the angular webapp under related/travetto.github.io
doc:mapping Generate module mapping for
email:compile CLI Entry point for running the email server
email:editor The email editor compilation service and output serving
email:test CLI Entry point for running the email server
eslint Command line support for eslint
eslint:register Writes the eslint configuration file
model:export Exports model schemas
model:install Installing models
openapi:client CLI for generating the cli client
openapi:spec CLI for outputting the open api spec to a local file
pack Standard pack support
pack:docker Standard docker support for pack
pack:lambda Standard lambda support for pack
pack:zip Standard zip support for pack
repo:exec Repo execution
repo:list Allows for listing of modules
repo:publish Publish all pending modules
repo:version Version all changed dependencies
repo:version-sync Enforces all packages to write out their versions and dependencies
run:double Doubles a number
scaffold Command to run scaffolding
service Allows for running services
test Launch test framework and execute tests
test:watch Invoke the test watcher
web:http Run a web server
web:rpc-client Generate the web-rpc client
`
This listing is from the Travetto monorepo, and represents the majority of tools that can be invoked from the command line.
This module also has a tight integration with the VSCode plugin, allowing the editing experience to benefit from the commands defined. The most commonly used commands will be the ones packaged with the framework, but its also very easy to create new commands. With the correct configuration, these commands will also be exposed within VSCode.
At it's heart, a cli command is the contract defined by what flags, and what arguments the command supports. Within the framework this requires three criteria to be met:
The file must be located in the support/ folder, and have a name that matches cli..ts
* The file must be a class that has a main method
* The class must use the @CliCommand decorator
Code: Basic Command
`typescript
import { CliCommand } from '@travetto/cli';
@CliCommand()
export class BasicCommand {
main() {
console.log('Hello');
}
}
`
Terminal: Basic Command Help
`bash
$ trv basic -h
Usage: basic [options]
Options:
-h, --help display help for command
`
has a direct mapping to the cli command name. This hard mapping allows for the framework to be able to know which file to invoke without needing to load all command-related files. Examples of mappings:
*
cli.test.ts maps to test
* maps to pack:docker
* maps to email:templateThe pattern is that underscores(_) translate to colons (:), and the
prefix, and .ts suffix are dropped.Binding Flags
@CliCommand is a wrapper for @Schema, and so every class that uses the @CliCommand decorator is now a full @Schema class. The fields of the class represent the flags that are available to the command.Code: Basic Command with Flag
`typescript
import { CliCommand } from '@travetto/cli';@CliCommand()
export class BasicCommand {
loud?: boolean;
main() {
console.log(this.loud ? 'HELLO' : 'Hello');
}
}
`Terminal: Basic Command with Flag Help
bash
$ trv basic:flag -hUsage: basic:flag [options]
Options:
-l, --loud
-h, --help display help for command
`As you can see the command now has the support of a basic boolean flag to determine if the response should be loud or not. The default value here is undefined/false, and so is an opt-in experience.
Terminal: Basic Command with Loud Flag
bash
$ trv basic:flag --loudHELLO
`The @CliCommand supports the following data types for flags:
* Boolean values
* Number values. The @Integer, @Float, @Precision, @Min and @Max decorators help provide additional validation.
* String values. @MinLength, @MaxLength, @Match and @Enum provide additional constraints
* Date values. The @Min and @Max decorators help provide additional validation.
* String lists. Same as String, but allowing multiple values.
* Numeric lists. Same as Number, but allowing multiple values.
Binding Arguments
The method is the entrypoint for the command, represents a series of parameters. Some will be required, some may be optional. The arguments support all types supported by the flags, and decorators can be provided using the decorators inline on parameters. Optional arguments in the method, will be optional at run time, and filled with the provided default values.Code: Basic Command with Arg
`typescript
import { CliCommand } from '@travetto/cli';
import { Max, Min } from '@travetto/schema';@CliCommand()
export class BasicCommand {
main(@Min(1) @Max(10) volume: number = 1) {
console.log(volume > 7 ? 'HELLO' : 'Hello');
}
}
`Terminal: Basic Command
bash
$ trv basic:arg -hUsage: basic:arg [options] [volume:number]
Options:
-h, --help display help for command
`Terminal: Basic Command with Invalid Loud Arg
bash
$ trv basic:arg 20Execution failed:
* Argument volume is greater than (10)
Usage: basic:arg [options] [volume:number]
Options:
-h, --help display help for command
`Terminal: Basic Command with Loud Arg > 7
bash
$ trv basic:arg 8HELLO
`Terminal: Basic Command without Arg
bash
$ trv basic:argHello
`Additionally, if you provide a field as an array, it will collect all valid values (excludes flags, and any arguments past a
).Code: Basic Command with Arg List
`typescript
import { CliCommand } from '@travetto/cli';
import { Max, Min } from '@travetto/schema';@CliCommand()
export class BasicCommand {
reverse?: boolean;
main(@Min(1) @Max(10) volumes: number[]) {
console.log(volumes.toSorted((a, b) => (a - b) * (this.reverse ? -1 : 1)).join(' '));
}
}
`Terminal: Basic Command
bash
$ trv basic:arg-list -hUsage: basic:arg-list [options]
Options:
-r, --reverse
-h, --help display help for command
`Terminal: Basic Arg List
bash
$ trv basic:arg-list 10 5 3 9 8 11 3 5 8 9 10
`Terminal: Basic Arg List with Invalid Number
bash
$ trv basic:arg-list 10 5 3 9 20 1Execution failed:
* Argument volumes[4] is greater than (10)
Usage: basic:arg-list [options]
Options:
-r, --reverse
-h, --help display help for command
`Terminal: Basic Arg List with Reverse
bash
$ trv basic:arg-list -r 10 5 3 9 8 110 9 8 5 3 1
`Customization
By default, all fields are treated as flags and all parameters of are treated as arguments within the validation process. Like the standard @Schema behavior, we can leverage the metadata of the fields/parameters to help provide additional customization/context for the users of the commands.Code: Custom Command with Metadata
`typescript
import { CliCommand } from '@travetto/cli';
import { Max, Min } from '@travetto/schema';/**
* Custom Argument Command
*/
@CliCommand()
export class CustomCommand {
/**
* The message to send back to the user
* @alias -m
* @alias --message
*/
text: string = 'hello';
main(@Min(1) @Max(10) volume: number = 1) {
console.log(volume > 7 ? this.text.toUpperCase() : this.text);
}
}
`Terminal: Custom Command Help
bash
$ trv custom:arg -hUsage: custom:arg [options] [volume:number]
Options:
-m, --message The message to send back to the user (default: "hello")
-h, --help display help for command
`Terminal: Custom Command Help with overridden Text
bash
$ trv custom:arg 10 -m cUsToMCUSTOM
`Terminal: Custom Command Help with default Text
bash
$ trv custom:arg 6hello
`Environment Variable Support
In addition to standard flag overriding (e.g. ), the command execution also supports allowing environment variables to provide values (secondary to whatever is passed in on the command line).Code: Custom Command with Env Var
`typescript
import { CliCommand } from '@travetto/cli';
import { Max, Min } from '@travetto/schema';/**
* Custom Argument Command
*/
@CliCommand()
export class CustomCommand {
/**
* The message to send back to the user
* @alias env.MESSAGE
*/
text: string = 'hello';
main(@Min(1) @Max(10) volume: number = 1) {
console.log(volume > 7 ? this.text.toUpperCase() : this.text);
}
}
`Terminal: Custom Command Help
bash
$ trv custom:env-arg -hUsage: custom:env-arg [options] [volume:number]
Options:
-t, --text The message to send back to the user (default: "hello")
-h, --help display help for command
`Terminal: Custom Command Help with default Text
bash
$ trv custom:env-arg 6hello
`Terminal: Custom Command Help with overridden Text
bash
$ MESSAGE=CuStOm trv custom:env-arg 10CUSTOM
`Terminal: Custom Command Help with overridden Text
bash
$ MESSAGE=CuStOm trv custom:env-arg 7CuStOm
`Flag File Support
Sometimes its also convenient, especially with commands that support a variety of flags, to provide easy access to pre-defined sets of flags. Flag files represent a snapshot of command line arguments and flags, as defined in a file. When referenced, these inputs are essentially injected into the command line as if the user had typed them manually.Code: Example Flag File
bash
--host localhost
--port 3306
--username app
`As you can see in this file, it provides easy access to predefine the host, port, and user flags.
Code: Using a Flag File
bash
npx trv call:db +=base --password
`The flag files can be included in one of a few ways:
*
- This translates into , which is a convenient shorthand.
* += - This is a path-related file that will be resolved from the module's location.
* +=/path/file.flags - This is an absolute path that will be read from the root of the file system.Ultimately, after resolution, the content of these files will be injected inline within the location.
Code: Final arguments after Flag File resolution
`bash
npx trv call:db --host localhost --port 3306 --username app --password
`VSCode Integration
By default, cli commands do not expose themselves to the VSCode extension, as the majority of them are not intended for that sort of operation. Web API does expose a cli target that will show up, to help run/debug a web application. Any command can mark itself as being a run target, and will be eligible for running from within the VSCode plugin. This is achieved by setting the runTarget field on the @CliCommand decorator. This means the target will be visible within the editor tooling.Code: Simple Run Target
`typescript
import { CliCommand } from '@travetto/cli';/**
* Simple Run Target
*/
@CliCommand({ runTarget: true })
export class RunCommand {
main(name: string) {
console.log(name);
}
}
`Advanced Usage
Code: Anatomy of a Command
typescript
export interface CliCommandShape {
/**
* Parsed state
*/
_parsed?: ParsedState;
/**
* Config
*/
_cfg?: CliCommandConfig;
/**
* Action target of the command
*/
main(...args: T): OrProm;
/**
* Run before main runs
*/
preMain?(): OrProm;
/**
* Extra help
*/
help?(): OrProm;
/**
* Run before help is displayed
*/
preHelp?(): OrProm;
/**
* Is the command active/eligible for usage
*/
isActive?(): boolean;
/**
* Run before binding occurs
*/
preBind?(): OrProm;
/**
* Run before validation occurs
*/
preValidate?(): OrProm;
/**
* Validation method
*/
validate?(...args: T): OrProm;
}
`$3
If the goal is to run a more complex application, which may include depending on Dependency Injection, we can take a look at Web API's target:Code: Simple Run Target
typescript
import { Runtime, toConcrete } from '@travetto/runtime';
import { DependencyRegistryIndex } from '@travetto/di';
import { CliCommand, type CliCommandShape } from '@travetto/cli';
import { NetUtil } from '@travetto/web';
import { Registry } from '@travetto/registry';import type { WebHttpServer } from '../src/types.ts';
/**
* Run a web server
*/
@CliCommand({ runTarget: true, with: { debugIpc: 'optional', restartOnChange: true, module: true, profiles: true } })
export class WebHttpCommand implements CliCommandShape {
/* Port to run on /
port?: number;
/* Kill conflicting port owner /
killConflict?: boolean = Runtime.localDevelopment;
preMain(): void {
if (this.port) {
process.env.WEB_HTTP_PORT =
${this.port};
}
} async main(): Promise {
await Registry.init();
const instance = await DependencyRegistryIndex.getInstance(toConcrete());
try {
const handle = await instance.serve();
return handle.complete;
} catch (err) {
const result = this.killConflict ? await NetUtil.freePortOnConflict(err) : undefined;
if (result?.processId) {
console.warn('Killed process owning port', result);
process.exitCode = 1; // Indicate error, restart will use if in that mode
return;
}
throw err;
}
}
}
`As noted in the example above,
is specified in this execution, with support for module, and env. These env flag is directly tied to the Runtime name defined in the Runtime module. The
module field is slightly more complex, but is geared towards supporting commands within a monorepo context. This flag ensures that a module is specified if running from the root of the monorepo, and that the module provided is real, and can run the desired command. When running from an explicit module folder in the monorepo, the module flag is ignored.$3
In addition to dependency injection, the command contract also allows for a custom validation function, which will have access to bound command (flags, and args) as well as the unknown arguments. When a command implements this method, any CliValidationError errors that are returned will be shared with the user, and fail to invoke the main method.Code: CliValidationError
`typescript
export interface CliValidationError {
/**
* The error message
*/
message: string;
/**
* Source of validation
*/
source?: 'flag' | 'arg' | 'custom';
};
`A simple example of the validation can be found in the
command:Code: Simple Validation Example
`typescript
async validate(): Promise {
const docFile = path.resolve(this.input);
if (!(await fs.stat(docFile).catch(() => false))) {
return { message: input: ${this.input} does not exist, source: 'flag' };
}
}
`CLI - service
The module provides the ability to start/stop/restart services as docker containers. This is meant to be used for development purposes, to minimize the effort of getting an application up and running. Services can be targeted individually or handled as a group.Terminal: Command Service
bash
$ trv service --helpUsage: service [options] [services...:string]
Options:
-h, --help display help for command
Available Services
--------------------
* dynamodb@3.1.0
* elasticsearch@9.2.3
* firestore@latest
* mongodb@8.2
* mysql@9.5
* postgresql@18.1
* redis@8.4
* s3@4.11.0
`A sample of all services available to the entire framework:
Terminal: All Services
bash
$ trv service statusService Version Status
-------------------------------------------------
dynamodb 3.1.0 Running 93af422e793a
elasticsearch 9.2.3 Running ed76ee063d13
firestore latest Running feec2e5e95b4
mongodb 8.2 Running 5513eba6734e
mysql 9.5 Running 307bc66d442a
postgresql 18.1 Running e78291e71040
redis 8.4 Running 77ba279b4e30
s3 4.11.0 Running fdacfc55b9e3
`$3
The services are defined as plain typescript files within the framework and can easily be extended:Code: Sample Service Definition
typescript
import type { ServiceDescriptor } from '@travetto/cli';const version = process.env.MONGO_VERSION || '8.2';
export const service: ServiceDescriptor = {
name: 'mongodb',
version,
port: 27017,
image:
mongo:${version}
};