ADAMMS CLI

CLI for ADAMMS – transformation rules and mappings management. Connects to the ADAMMS API to manage projects, systems, tables, fields, rules, and config items.

Prerequisites

• Node.js >= 18
• Running Adamms app (e.g. locally pnpm dev in the main project, or hosted somewhere)

Installation (unpublished / local)

Build and run directly:

cd packages/adamms-cli
pnpm run build
node dist/cli.js --help

Or from the repo root:

node packages/adamms-cli/dist/cli.js --help

Global options

These options apply to all commands and can be placed before the subcommand:

| Option | Short | Description | |--------|-------|-------------| | --base-url <url> | -b | Override API base URL (e.g. http://localhost:3000) | | --token <token> | -t | Override auth token | | --pretty | | Pretty-print JSON output (indented) | | --help | -h | Display help | | --agent-help | -ah | Output markdown step-by-step guide for agents |

Configuration

Config is loaded from (in order):

1. Environment variables: ADAMMS_BASE_URL, ADAMMS_TOKEN
2. Local config: ./.adamms/config.json (relative to cwd)
3. Global config: ~/.adamms/config.json

config

| Command | Description | |---------|-------------| | config set <key> <value> | Set config value | | config show | Show current config (token masked) |

config set options:

| Option | Description | |--------|-------------| | -g, --global | Use global config instead of local |

Keys: base-url (or baseUrl), token

Examples:

adamms config set base-url http://localhost:3000
adamms config set token <your-token>
adamms config show

Authentication

auth

Create a machine token (saves to config). Requires base URL; token not needed.

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --email <email> | -e | Yes | User email | | --password <password> | -p | Yes | User password | | --name <name> | -n | No | Token name | | --expires-in-days <days> | | No | Token expiry in days |

Example:

adamms -b http://localhost:3000 auth --email [email protected] --password secret

auth whoami

Show current user. Requires base URL and token.

Context

context show

Show current active project and source/target systems. Requires base URL and token.

context set

Set current project and/or system. Prompts interactively if not provided.

| Option | Short | Description | |--------|-------|-------------| | --project <id> | -p | Project ID | | --system <id> | -s | System ID |

Projects

All project commands require base URL and token.

| Command | Description | |---------|-------------| | projects list | List projects | | projects get <id> | Get project by ID | | projects create | Create project | | projects update <id> | Update project | | projects delete <id> | Delete project |

projects list options:

| Option | Short | Description | |--------|-------|-------------| | --user-id <id> | -u | Filter by user ID |

projects create options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --name <name> | -n | Yes | Project name | | --source-system <id> | | No | Source system ID | | --target-system <id> | | No | Target system ID | | --jira-url <url> | | No | Jira URL |

projects update options:

| Option | Short | Description | |--------|-------|-------------| | --name <name> | -n | Project name | | --source-system <id> | | Source system ID | | --target-system <id> | | Target system ID | | --jira-url <url> | | Jira URL |

Systems

All system commands require base URL and token.

| Command | Description | |---------|-------------| | systems list | List systems | | systems get <id> | Get system by ID | | systems create | Create system | | systems update <id> | Update system | | systems delete <id> | Delete system |

systems list options:

| Option | Short | Description | |--------|-------|-------------| | --user-id <id> | -u | Filter by user ID |

systems create options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --name <name> | -n | Yes | System name | | --type <type> | -t | No | System type: Source or Target (default: Source) |

systems update options:

| Option | Short | Description | |--------|-------|-------------| | --name <name> | -n | System name |

Tables

All table commands require base URL and token.

| Command | Description | |---------|-------------| | tables list | List tables | | tables get <id> | Get table by ID | | tables create | Create table | | tables update <id> | Update table | | tables delete <id> | Delete table |

tables list options:

| Option | Short | Description | |--------|-------|-------------| | --system-id <id> | -s | System ID (uses current context if omitted) | | --source | | Filter by source system of active project | | --target | | Filter by target system of active project | | --filter <value> | -f | Filter value |

tables create options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --system-id <id> | -s | Yes | System ID | | --name <name> | -n | Yes | Table name | | --description <desc> | -d | No | Description | | --functional-area <area> | | No | Functional area | | --sub-area <area> | | No | Sub area |

tables update options:

| Option | Short | Description | |--------|-------|-------------| | --name <name> | -n | Table name | | --description <desc> | -d | Description |

Fields

All field commands require base URL and token.

| Command | Description | |---------|-------------| | fields list | List fields | | fields get <id> | Get field by ID | | fields create | Create field | | fields update <id> | Update field | | fields delete <id> | Delete field |

fields list options:

| Option | Short | Description | |--------|-------|-------------| | --system-id <id> | -s | System ID (uses current context if omitted) | | --table-id <id> | | Filter by table ID | | --source | | Filter by source system of active project | | --target | | Filter by target system of active project | | --filter <value> | -f | Filter value |

fields create options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --system-id <id> | -s | Yes | System ID | | --tablename <name> | -t | Yes | Table name | | --fieldname <name> | -f | Yes | Field name | | --datatype <type> | -d | No | Data type (default: VARCHAR) | | --length <n> | -l | No | Length | | --nullable | | No | Field is nullable | | --description <desc> | | No | Description | | --validation-code <code> | | No | Validation code |

fields update options:

| Option | Short | Description | |--------|-------|-------------| | --description <desc> | -d | Description | | --validation-code <code> | | Validation code |

Field values

Field values are value/meaning pairs for fields (e.g. code-to-description mappings). All commands require base URL and token. Create, update, and delete require admin access.

| Command | Description | |---------|-------------| | field-values list | List field values for a field | | field-values get <id> | Get field value by ID | | field-values create | Create field value | | field-values update <id> | Update field value | | field-values delete <id> | Delete field value |

field-values list options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --field-id <id> | -f | Yes | Field ID |

field-values create options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --field-id <id> | -f | Yes | Field ID | | --value <value> | -v | Yes | Value | | --meaning <meaning> | -m | Yes | Meaning |

field-values update options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --value <value> | -v | No | Value | | --meaning <meaning> | -m | No | Meaning (at least one of --value or --meaning required) |

Example:

adamms field-values list -f <field-id>
adamms field-values create -f <field-id> -v "01" -m "Active"
adamms field-values update <id> --meaning "Active status"

Rules (transformation rules)

All rule commands require base URL and token.

| Command | Description | |---------|-------------| | rules list | List rules | | rules get <id> | Get rule by ID | | rules create | Create rule | | rules update <id> | Update rule | | rules delete <id> | Delete rule |

rules list options:

| Option | Short | Description | |--------|-------|-------------| | --project-id <id> | -p | Project ID (uses current context if omitted) | | --filter <value> | -f | Filter value |

rules create options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --project-id <id> | -p | Yes | Project ID | | --target-table <table> | -t | Yes | Target table | | --mapping-code <code> | -m | Yes | Mapping code (JSON string or plain code) | | --status <status> | -s | Yes | Status: open, in progress, done, obsolete | | --comment <comment> | -c | Yes | Changelog comment (recorded as agent change) | | --target-field <field> | | No | Target field | | --validation-code <code> | | No | Validation code | | --type <type> | | No | Type: FieldMapping or SelectionRule | | --description <desc> | | No | Description | | --selection-rule-id <id> | | No | Selection rule ID | | --ticket-id <id> | | No | Changelog ticket ID (e.g. TICKET-123) |

rules update options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --status <status> | -s | No | Status | | --mapping-code <code> | -m | No | Mapping code (JSON) | | --description <desc> | | No | Description | | --comment <comment> | -c | Yes (when updating) | Changelog comment (recorded as agent change) | | --ticket-id <id> | | No | Changelog ticket ID (e.g. TICKET-123) |

Config items

All config-item commands require base URL and token.

| Command | Description | |---------|-------------| | config-items list | List config items | | config-items get <id> | Get config item by ID | | config-items create | Create config item | | config-items update <id> | Update config item | | config-items delete <id> | Delete config item |

config-items list options:

| Option | Short | Description | |--------|-------|-------------| | --project-id <id> | -p | Project ID (uses current context if omitted) | | --category <cat> | -c | Category: Global or Local | | --filter <value> | -f | Filter value |

config-items create options:

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --name <name> | -n | Yes | Name | | --value <value> | -v | Yes | Value | | --category <cat> | -c | Yes | Category: Global or Local | | --project-id <id> | -p | No | Project ID (for Local) | | --description <desc> | -d | No | Description | | --type <type> | -t | No | Type | | --comment <comment> | | No | Comment |

config-items update options:

| Option | Short | Description | |--------|-------|-------------| | --name <name> | -n | Name | | --value <value> | -v | Value | | --description <desc> | -d | Description |

Analyse (CSV)

Analyzes CSV columns for patterns, datatypes, value-lists, and pseudo-code validations. Does not require base URL or token.

| Option | Short | Required | Description | |--------|-------|----------|-------------| | --input <path> | -i | Yes | Input CSV file path | | --output <path> | -o | No | Output JSON file path (default: adamms_analyse_output.json) |

Example:

adamms analyse -i data.csv -o report.json

Output is written to the specified file. Use --pretty for pretty-printed JSON.

Quick start

# 1. Build the CLI
cd packages/adamms-cli && pnpm run build

# 2. Ensure the app is running (in another terminal)
pnpm dev

# 3. Authenticate (saves token to config)
node dist/cli.js -b http://localhost:3000 auth --email [email protected] --password yourpassword

# 4. Set base URL in config so you don't need -b every time
node dist/cli.js config set base-url http://localhost:3000

# 5. Run commands
node dist/cli.js projects list
node dist/cli.js context show

Output format

All commands output JSON to stdout. Success responses use { "data": ... }. Errors use { "error": { "code": "...", "message": "..." } } and exit with code 1.