15 minlesson

CLI Walkthrough

CLI Walkthrough

This lesson walks through a complete CLI session from first login to creating and validating your first module file. Follow along in your terminal. You will use these commands every day as a CXTMS developer.

Prerequisites

  • Node.js 18 or later installed
  • Access credentials for a CXTMS development server
  • Your organization ID (ask your team lead if unsure)

Step 1: Verify the CLI is Available

Confirm npx can reach the CLI before starting:

bash
1npx cxtms --version

Expected output:

cxtms/2.1.0 win32-x64 node-v20.11.0

If you see a version number, you are ready. If the command fails, verify your Node.js installation with node --version.

Step 2: Log In to the Development Server

Authenticate with your development environment:

bash
1npx cxtms login https://tms-v3-dev.usatrt.com

The CLI opens your default browser to the CXTMS login page. Sign in with your credentials. After successful authentication, the browser shows a confirmation message and the CLI prints:

1✓ Logged in successfully
2  Server: https://tms-v3-dev.usatrt.com
3  User:   you@yourcompany.com
4  Session saved to ~/.cxtms/my-project/.session.json

Close the browser tab and return to your terminal.

Step 3: List Available Organizations

See which organizations are available on the server:

bash
1npx cxtms orgs list

Expected output:

1Organizations on https://tms-v3-dev.usatrt.com:
2  ID    Name                    Status
3  ----  ----------------------  --------
4  1     Demo Freight Co.        Active
5  42    Acme Logistics Dev      Active
6

7Active org: (none selected)

Step 4: Select Your Working Organization

Set the active organization. You can use the interactive picker:

bash
1npx cxtms orgs select

Or set it directly by ID (faster once you know the ID):

bash
1npx cxtms orgs use 42

Confirm the context is correct:

bash
1npx cxtms orgs use

Expected output:

1Current context:
2  Server:  https://tms-v3-dev.usatrt.com
3  Org:     42 — Acme Logistics Dev
4  App:     acme-logistics (v1.4.2)

All subsequent server commands will target organization 42 until you change it.

Step 5: Explore Available Commands

Get the full command list:

bash
1npx cxtms --help

Explore a specific command's options:

bash
1npx cxtms create --help
2npx cxtms publish --help

List all available module and workflow schema names:

bash
1npx cxtms list

This shows every component the CLI knows about — module templates, workflow task schemas, and their schema names.

Step 6: Check Module Templates

Before creating a module, explore what templates are available and what the grid template produces:

bash
1# See an example of the grid template structure
2npx cxtms example dataGrid

The output shows an annotated YAML snippet for a data grid component — the same structure that will be generated when you scaffold a grid module.

Check the schema for form fields to understand what field types are supported:

bash
1npx cxtms schema formField

Step 7: Scaffold a Sample Module

Create a project directory and scaffold your first module. This example creates a grid that lists Orders:

bash
1# Create a feature directory structure
2mkdir -p features/shipments/modules
3

4# Scaffold a grid module with the --feature flag (auto-places in features/shipments/modules/)
5npx cxtms create module "Order List" --template grid --feature shipments

Expected output:

✓ Created features/shipments/modules/order-list-module.yaml

Open the generated file in your editor. Notice it contains:

  • A moduleId UUID generated automatically
  • entityKind: Order as the default entity
  • A views array with a sample data grid view
  • A routes array registering the module in the navigation
  • Placeholder column definitions to customize

Step 8: Validate the Generated File

Validate the newly created file to confirm it is schema-valid before making any changes:

bash
1npx cxtms features/shipments/modules/order-list-module.yaml

Expected output:

✓ features/shipments/modules/order-list-module.yaml — valid

Now make a deliberate mistake to see what a validation error looks like. Open the file and delete the required field property from one of the column definitions, then validate again:

bash
1npx cxtms features/shipments/modules/order-list-module.yaml

Example error output:

1✗ features/shipments/modules/order-list-module.yaml
2  [views[0].columns[0]] Required property 'field' is missing

The error message tells you exactly which path in the YAML is invalid. Fix the mistake and re-validate before continuing.

Step 9: Explore Component Schemas

Before customizing your module's columns, check what properties a column definition supports:

bash
1npx cxtms schema columnDef

To see what filter types are available for grid views:

bash
1npx cxtms schema filterDef

To see an example of a complete data grid view with columns and filters:

bash
1npx cxtms example dataGrid

Use these commands any time you need to look up what properties are available or what values an enum accepts. The schemas are always in sync with the server's current version — you never need to dig through documentation.

Step 10: Validate All Features

When working across multiple feature directories, validate everything at once:

bash
1npx cxtms features/

Expected output when all files are valid:

1✓ features/shipments/modules/order-list-module.yaml — valid
2  1 file(s) validated, 0 error(s)

This is the command to run before every publish or deploy to catch any issues across the entire project.

What's Next

You now have a working CLI setup and have completed the essential workflow:

  1. Login → 2. Select org → 3. Scaffold → 4. Validate → 5. Customize → 6. Re-validate → 7. Deploy

In the upcoming topics, you will learn how to customize module YAML files to build real Order and Contact screens, and how to author workflow YAML files to automate business processes.

For reference, the full set of auth and org commands covered in this topic:

bash
1npx cxtms login <server>         # OAuth2 interactive login
2npx cxtms logout                 # End session
3npx cxtms pat create "<name>"    # Create a PAT for CI/CD
4npx cxtms pat list               # List active PATs
5npx cxtms pat revoke <id>        # Revoke a PAT
6npx cxtms orgs list              # List organizations
7npx cxtms orgs select            # Interactive org picker
8npx cxtms orgs use <id>          # Set active org by ID
9npx cxtms orgs use               # Show current context