@ai-digital-factory/lmt-cli 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +115 -86
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,151 +1,180 @@
|
|
|
1
1
|
# Live Market Terminal CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Use the published [`@ai-digital-factory/lmt-cli`](https://www.npmjs.com/package/@ai-digital-factory/lmt-cli) package to log in to Live Market Terminal, manage Operator Sessions, and complete Zerodha login from your terminal. The executable is `lmt`; `live-market-terminal` is an alias with the same commands.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Install or update
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
Requires Node.js 22 or later. Install without a source checkout:
|
|
7
|
+
Requires **Node.js 22 or later**, with npm and npx available on your PATH. No source checkout, pnpm, build step, or local configuration file is needed for the published package.
|
|
10
8
|
|
|
11
9
|
```sh
|
|
12
|
-
|
|
10
|
+
node --version
|
|
11
|
+
npm install --global @ai-digital-factory/lmt-cli@latest
|
|
13
12
|
lmt --help
|
|
14
|
-
lmt interactive --env dev --profile my-dev-session
|
|
15
|
-
lmt status --env dev --profile my-dev-session
|
|
16
13
|
```
|
|
17
14
|
|
|
18
|
-
|
|
19
|
-
and headless command syntax. Provision the protected SMS read credential with
|
|
20
|
-
`lmt interactive credential provision --env dev`, or use
|
|
21
|
-
`lmt credential provision --env dev --profile default --credential-stdin` with
|
|
22
|
-
protected stdin as described below. Installation never provisions credentials.
|
|
23
|
-
The package includes canonical non-secret local/dev Origins, Gate scopes, and
|
|
24
|
-
SMS endpoint; it needs no repository configuration in the current directory.
|
|
25
|
-
Local use still requires a running local stack. Production targets remain unavailable.
|
|
15
|
+
Run the same install command to update to the latest published version. To check your installed version:
|
|
26
16
|
|
|
27
|
-
|
|
17
|
+
```sh
|
|
18
|
+
npm list --global @ai-digital-factory/lmt-cli --depth=0
|
|
19
|
+
```
|
|
28
20
|
|
|
29
|
-
The
|
|
30
|
-
current `main`, tests the CLI, builds a standalone package with bundled private
|
|
31
|
-
contracts, selects the next npm patch, and tests a clean installation of the exact
|
|
32
|
-
tarball it publishes publicly under `latest`. Node 22 and pnpm 10.33.3 match CI.
|
|
21
|
+
The package includes the non-secret Origins, Gate scopes, and SMS endpoint. Choose `--env dev` for the deployed dev service, or `--env local` for a running local stack. Only `local` and `dev` are supported; `prod` is rejected. Installing the CLI does not start services or provision credentials.
|
|
33
22
|
|
|
34
|
-
|
|
35
|
-
It must be able to read `NPM_TOKEN` from SMS scope `infra`, at Vault
|
|
36
|
-
`secret/data/infra/NPM_TOKEN` with field `value`. The endpoint and scope are
|
|
37
|
-
non-secret repository configuration. The existing npm token needs publishing
|
|
38
|
-
permission for `@ai-digital-factory/lmt-cli`; it is masked and passed only to the
|
|
39
|
-
publishing step. No credential values are included in the package.
|
|
23
|
+
## Quick start: interactive dev login
|
|
40
24
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
only in the temporary publishing artifact, with no bump commit, git tag, GitHub
|
|
44
|
-
Release, Origin Version, or deployment. A retry after successful npm publication
|
|
45
|
-
selects another patch, since published npm versions are immutable.
|
|
25
|
+
1. Obtain your Operator Login username and password. For headless login and Operator Session validation, also obtain an SMS read credential authorized to read `live-market-terminal-operator-directory` in the selected Gate scope from your administrator.
|
|
26
|
+
2. If using those SMS-backed commands, provision the credential once using the masked prompt:
|
|
46
27
|
|
|
47
|
-
|
|
28
|
+
```sh
|
|
29
|
+
lmt interactive credential provision --env dev
|
|
30
|
+
```
|
|
48
31
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
tarball=$(bash .github/scripts/pack-lmt-cli.sh /tmp/lmt-cli-package)
|
|
52
|
-
node .github/scripts/test-lmt-cli-package.mjs "$tarball"
|
|
53
|
-
```
|
|
32
|
+
Paste the SMS read credential and press Enter. After `SMS credential saved.` appears, press Ctrl+C to leave the provisioning screen. The credential is shared across profiles.
|
|
33
|
+
3. Open the interactive terminal:
|
|
54
34
|
|
|
55
|
-
|
|
35
|
+
```sh
|
|
36
|
+
lmt interactive --env dev --profile my-dev-session
|
|
37
|
+
```
|
|
56
38
|
|
|
57
|
-
|
|
39
|
+
Enter your Operator Login username and password when prompted. This interactive login uses the credentials you enter; it does not require reading them from SMS. A valid saved session resumes automatically.
|
|
40
|
+
4. Use the menu to **Login with Zerodha**, **Check Operator Session**, **Validate Operator Session**, or **Logout Operator Session**. Zerodha login prompts for the current six-digit OTP. Validation requires the provisioned SMS credential.
|
|
58
41
|
|
|
59
|
-
|
|
42
|
+
Press Enter to submit each prompt. At the Operator password prompt, Escape returns to the username; Ctrl+U clears either field. Passwords remain masked. Press Ctrl+C to exit the terminal; use the logout command or menu action when you want to revoke the Operator Session.
|
|
43
|
+
|
|
44
|
+
Interactive mode defaults to `--env local --profile default` when these options are omitted. Keep the same environment and profile across commands to reuse a session:
|
|
60
45
|
|
|
61
46
|
```sh
|
|
62
|
-
|
|
63
|
-
pnpm cli --profile default
|
|
64
|
-
pnpm cli --env dev --profile my-dev-session
|
|
47
|
+
lmt status --env dev --profile my-dev-session
|
|
65
48
|
```
|
|
66
49
|
|
|
67
|
-
|
|
50
|
+
## Headless Operator login and sessions
|
|
51
|
+
|
|
52
|
+
Headless commands require **both `--env` and `--profile`**. They never prompt for input. Provision the SMS credential using the masked interactive command above, then run:
|
|
68
53
|
|
|
69
54
|
```sh
|
|
70
|
-
|
|
55
|
+
lmt login --env dev --profile my-dev-session
|
|
56
|
+
lmt status --env dev --profile my-dev-session
|
|
57
|
+
lmt validate operator-session --env dev --profile my-dev-session
|
|
58
|
+
lmt logout --env dev --profile my-dev-session
|
|
71
59
|
```
|
|
72
60
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
## Headless use
|
|
61
|
+
`login` reads the configured Operator's username and password from the selected Gate scope's SMS Operator Directory and authenticates through Gate. SMS reads invoke `@ai-digital-factory/sms-cli@0.1.2` through npx, so npm registry access is needed when it is not cached. `status` verifies the saved Operator Session with Gate and the Broker-backed operators route; it does not confirm Zerodha login. Validation exercises login and session behavior using a temporary profile, logs out its temporary sessions, and removes only its temporary records.
|
|
76
62
|
|
|
77
|
-
|
|
63
|
+
`logout` revokes the Operator Session through Gate and clears its saved cookies and pending Zerodha attempt. If Gate cannot confirm logout, the command fails and retains cookies for retry. Other profiles, the shared SMS credential, and Broker-owned SMS access tokens remain intact.
|
|
78
64
|
|
|
79
|
-
|
|
65
|
+
For automated credential provisioning, pipe one non-empty credential line through protected stdin:
|
|
80
66
|
|
|
81
67
|
```sh
|
|
82
|
-
|
|
83
|
-
printf '%s\n' "$SMS_CREDENTIAL" | pnpm -s cli:headless credential provision --env dev --profile my-dev-session --credential-stdin
|
|
84
|
-
unset SMS_CREDENTIAL
|
|
68
|
+
lmt credential provision --env dev --profile my-dev-session --credential-stdin < /path/to/protected-sms-credential-file
|
|
85
69
|
```
|
|
86
70
|
|
|
87
|
-
|
|
71
|
+
Replace the path with an owner-readable credential file supplied by your secret-management process. Keep SMS credentials, passwords, and cookies out of command arguments. Provisioning saves the credential locally; it does not verify SMS access.
|
|
72
|
+
|
|
73
|
+
## Headless Zerodha login
|
|
74
|
+
|
|
75
|
+
First establish an Operator Session with `lmt login` or interactive login using the same environment and profile. Zerodha credentials stay on Broker. Submit the current six-digit OTP:
|
|
88
76
|
|
|
89
77
|
```sh
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
pnpm -s cli:headless status --env dev --profile my-dev-session
|
|
93
|
-
pnpm -s cli:headless validate operator-session --env dev --profile my-dev-session
|
|
78
|
+
lmt zerodha login --env dev --profile my-dev-session --otp CURRENT_OTP
|
|
79
|
+
lmt zerodha status --env dev --profile my-dev-session
|
|
94
80
|
```
|
|
95
81
|
|
|
96
|
-
|
|
82
|
+
Replace `CURRENT_OTP` with the actual six-digit code. `zerodha login` starts or resumes the profile's login attempt and verifies the resulting Zerodha Session through Gate. The OTP is not stored or included in JSON results or diagnostics; it is passed as a command argument. `--otp-stdin` is unsupported.
|
|
97
83
|
|
|
98
|
-
|
|
84
|
+
To start the challenge before obtaining the OTP:
|
|
99
85
|
|
|
100
86
|
```sh
|
|
101
|
-
|
|
87
|
+
lmt zerodha login --env dev --profile my-dev-session
|
|
102
88
|
```
|
|
103
89
|
|
|
104
|
-
|
|
90
|
+
When human input is needed, this returns `outcome: "blocked"`, `reason: "awaiting_otp"`, and exit code `4`. Repeat `zerodha login` with `--otp CURRENT_OTP` once the code is available. Attempt IDs are remembered automatically for the selected profile and target.
|
|
105
91
|
|
|
106
|
-
|
|
92
|
+
Additional commands for an existing attempt:
|
|
107
93
|
|
|
108
94
|
```sh
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
pnpm -s cli:headless validate operator-session --env local --profile smoke-local
|
|
112
|
-
|
|
113
|
-
pnpm -s cli:headless login --env dev --profile smoke-dev
|
|
114
|
-
pnpm -s cli:headless status --env dev --profile smoke-dev
|
|
115
|
-
pnpm -s cli:headless validate operator-session --env dev --profile smoke-dev
|
|
95
|
+
lmt zerodha observe --env dev --profile my-dev-session
|
|
96
|
+
lmt zerodha otp --env dev --profile my-dev-session --otp CURRENT_OTP
|
|
116
97
|
```
|
|
117
98
|
|
|
118
|
-
|
|
99
|
+
`observe` and `otp` optionally accept `--attempt ID` to override the remembered attempt. Invalid OTPs report Broker's rejection message and retry count. Successful login, Operator logout, and Operator Session replacement or rejection clear the remembered attempt.
|
|
119
100
|
|
|
120
|
-
|
|
101
|
+
## Profiles and local use
|
|
121
102
|
|
|
122
|
-
|
|
103
|
+
Profiles save Client Identity and Operator Session cookies across invocations. Sessions are isolated by profile, environment, canonical Origin, and configured Operator. Profile names must be 1–64 letters, digits, dots, underscores, or hyphens, starting with a letter or digit.
|
|
123
104
|
|
|
124
|
-
|
|
105
|
+
Storage is `~/.lmt/secrets.pem`: a protected JSON file containing the shared SMS credential, per-profile cookies, and pending Zerodha attempt IDs. The CLI enforces owner-only permissions and migrates legacy storage automatically. Do not share this file or include it in logs or version control.
|
|
125
106
|
|
|
126
|
-
|
|
107
|
+
For local use, first start Web, Gate, and Broker from a configured source checkout with `pnpm dev:local` in `live-market-terminal/`. The installed CLI uses the bundled canonical local Origin (`http://127.0.0.1:5173`) through Web's `/api` proxy; it does not fall back to a different port. The CLI's SMS read credential is separate from the service credential used by Gate and Broker.
|
|
127
108
|
|
|
128
109
|
```sh
|
|
129
|
-
|
|
110
|
+
lmt interactive --env local --profile my-local-session
|
|
111
|
+
lmt status --env local --profile my-local-session
|
|
130
112
|
```
|
|
131
113
|
|
|
132
|
-
|
|
114
|
+
## Output, deadlines, and troubleshooting
|
|
115
|
+
|
|
116
|
+
Headless commands write one versioned JSON object per line to stdout; diagnostics go to stderr. Inspect `outcome`, `reason`, and, on failure, `error`. Use the process exit code for automation:
|
|
133
117
|
|
|
134
|
-
|
|
118
|
+
| Exit code | Meaning | Next step |
|
|
119
|
+
| --- | --- | --- |
|
|
120
|
+
| `0` | Success or validation pass | Continue. |
|
|
121
|
+
| `1` | Action failure | Read the diagnostic; check SMS permissions or service reachability. |
|
|
122
|
+
| `2` | Invalid invocation or target | Check `lmt --help`; supply `local` or `dev` and a valid profile. |
|
|
123
|
+
| `3` | Operator Login required | Run `login` or interactive login with the same environment and profile. |
|
|
124
|
+
| `4` | Validation blocked or Zerodha awaiting OTP | Read `reason`; for `awaiting_otp`, repeat Zerodha login with the current OTP. |
|
|
125
|
+
|
|
126
|
+
Actions default to 30 seconds; validation defaults to 2 minutes. Headless actions and validation accept a finite deadline between 1 millisecond and 10 minutes:
|
|
135
127
|
|
|
136
128
|
```sh
|
|
137
|
-
|
|
129
|
+
lmt status --env dev --profile my-dev-session --timeout 45s
|
|
130
|
+
lmt validate operator-session --env dev --profile my-dev-session --timeout 2m
|
|
138
131
|
```
|
|
139
132
|
|
|
140
|
-
|
|
133
|
+
- **`lmt: command not found`:** confirm the global installation with `npm list --global @ai-digital-factory/lmt-cli --depth=0` and add npm's global executable directory to PATH (`npm prefix --global`, then `bin/` on macOS/Linux).
|
|
134
|
+
- **Missing SMS credential:** run `lmt interactive credential provision --env dev` and retry. The credential is shared, but it needs access to the scope used by your chosen environment.
|
|
135
|
+
- **SMS unavailable or invalid Operator Directory:** check the credential's read access and the selected Gate scope's Operator Directory with your administrator.
|
|
136
|
+
- **Session expired or rejected:** the CLI clears rejected session cookies. Log in again explicitly using the same profile and environment.
|
|
137
|
+
- **Origin or Broker unavailable:** check the selected deployment. For local use, keep the full stack running at the canonical Origin. `status` requires Broker to be available even when Gate still accepts the session.
|
|
138
|
+
|
|
139
|
+
## Run from a source checkout
|
|
140
|
+
|
|
141
|
+
For contributors, from `live-market-terminal/`:
|
|
141
142
|
|
|
142
143
|
```sh
|
|
143
|
-
pnpm
|
|
144
|
-
pnpm -s cli:headless
|
|
144
|
+
pnpm cli --env dev --profile my-dev-session
|
|
145
|
+
pnpm -s cli:headless status --env dev --profile my-dev-session
|
|
146
|
+
pnpm --filter @ai-digital-factory/lmt-cli interactive credential provision --env dev
|
|
145
147
|
```
|
|
146
148
|
|
|
147
|
-
|
|
149
|
+
These repository scripts rebuild the CLI. The published commands above run directly from the installed package. The CLI sets `NODE_USE_ENV_PROXY=0` on startup so local Gate requests are not sent through `HTTP(S)_PROXY`.
|
|
148
150
|
|
|
149
|
-
|
|
151
|
+
## Maintain the npm package
|
|
150
152
|
|
|
151
|
-
|
|
153
|
+
The **Release LMT CLI** GitHub Action is dispatched manually on `main`. It builds
|
|
154
|
+
current `main`, tests the CLI, builds a standalone package with bundled private
|
|
155
|
+
contracts, selects the next npm patch, and tests a clean installation of the exact
|
|
156
|
+
tarball it publishes publicly under `latest`. Node 22 and pnpm 10.33.3 match CI.
|
|
157
|
+
|
|
158
|
+
Only `SMS_CREDENTIAL` is configured as a GitHub Actions secret for this workflow.
|
|
159
|
+
It must be able to read `NPM_TOKEN` from SMS scope `infra`, at Vault
|
|
160
|
+
`secret/data/infra/NPM_TOKEN` with field `value`. The endpoint and scope are
|
|
161
|
+
non-secret repository configuration. The existing npm token needs publishing
|
|
162
|
+
permission for `@ai-digital-factory/lmt-cli`; it is masked and passed only to the
|
|
163
|
+
publishing step. No credential values are included in the package.
|
|
164
|
+
|
|
165
|
+
First publication uses `0.1.0`; later runs increment the highest published stable
|
|
166
|
+
version's patch. Registry/authentication failures stop the release. Versions change
|
|
167
|
+
only in the temporary publishing artifact, with no bump commit, git tag, GitHub
|
|
168
|
+
Release, Origin Version, or deployment. A retry after successful npm publication
|
|
169
|
+
selects another patch, since published npm versions are immutable. npm can accept
|
|
170
|
+
an upload before public registry processing finishes; the action polls for visibility
|
|
171
|
+
for five minutes. If confirmation times out after a successful upload, check npm
|
|
172
|
+
before rerunning the release to avoid publishing an unnecessary patch.
|
|
173
|
+
|
|
174
|
+
To reproduce the packaging checks from the repository root:
|
|
175
|
+
|
|
176
|
+
```sh
|
|
177
|
+
(cd live-market-terminal && pnpm --filter @ai-digital-factory/lmt-cli package:build)
|
|
178
|
+
tarball=$(bash .github/scripts/pack-lmt-cli.sh /tmp/lmt-cli-package)
|
|
179
|
+
node .github/scripts/test-lmt-cli-package.mjs "$tarball"
|
|
180
|
+
```
|