indraq_cli 2.7.1 → 2.7.9

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.
Files changed (100) hide show
  1. package/README.md +1167 -419
  2. package/cloud-api/README.md +6 -0
  3. package/cloud-api/dist/index.js +315 -53
  4. package/cloud-api/package.json +1 -1
  5. package/cloud-api/sql/013_ota_tester_enrollment.sql +55 -0
  6. package/cloud-api/src/index.ts +229 -44
  7. package/dist/cli/help-content.d.ts.map +1 -1
  8. package/dist/cli/help-content.js +20 -7
  9. package/dist/cli/help-content.js.map +1 -1
  10. package/dist/modules/cloud/services/cloud-jenkins.service.d.ts +6 -1
  11. package/dist/modules/cloud/services/cloud-jenkins.service.d.ts.map +1 -1
  12. package/dist/modules/cloud/services/cloud-jenkins.service.js +62 -5
  13. package/dist/modules/cloud/services/cloud-jenkins.service.js.map +1 -1
  14. package/dist/modules/mobile/commands/build-mobile.command.d.ts +1 -0
  15. package/dist/modules/mobile/commands/build-mobile.command.d.ts.map +1 -1
  16. package/dist/modules/mobile/commands/build-mobile.command.js +41 -23
  17. package/dist/modules/mobile/commands/build-mobile.command.js.map +1 -1
  18. package/dist/modules/mobile/commands/configure-mobile.command.js +1 -1
  19. package/dist/modules/mobile/commands/configure-mobile.command.js.map +1 -1
  20. package/dist/modules/mobile/commands/mobile-build-wizard.command.d.ts +15 -0
  21. package/dist/modules/mobile/commands/mobile-build-wizard.command.d.ts.map +1 -0
  22. package/dist/modules/mobile/commands/mobile-build-wizard.command.js +134 -0
  23. package/dist/modules/mobile/commands/mobile-build-wizard.command.js.map +1 -0
  24. package/dist/modules/mobile/commands/mobile-environment.command.d.ts.map +1 -1
  25. package/dist/modules/mobile/commands/mobile-environment.command.js +4 -6
  26. package/dist/modules/mobile/commands/mobile-environment.command.js.map +1 -1
  27. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts +2 -0
  28. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts.map +1 -1
  29. package/dist/modules/mobile/commands/mobile-prebuild.command.js +24 -18
  30. package/dist/modules/mobile/commands/mobile-prebuild.command.js.map +1 -1
  31. package/dist/modules/mobile/commands/ota.command.d.ts +1 -0
  32. package/dist/modules/mobile/commands/ota.command.d.ts.map +1 -1
  33. package/dist/modules/mobile/commands/ota.command.js +67 -13
  34. package/dist/modules/mobile/commands/ota.command.js.map +1 -1
  35. package/dist/modules/mobile/commands/testers.command.d.ts +6 -0
  36. package/dist/modules/mobile/commands/testers.command.d.ts.map +1 -0
  37. package/dist/modules/mobile/commands/testers.command.js +143 -0
  38. package/dist/modules/mobile/commands/testers.command.js.map +1 -0
  39. package/dist/modules/mobile/config/mobile-config.d.ts +1 -0
  40. package/dist/modules/mobile/config/mobile-config.d.ts.map +1 -1
  41. package/dist/modules/mobile/config/mobile-config.js +6 -1
  42. package/dist/modules/mobile/config/mobile-config.js.map +1 -1
  43. package/dist/modules/mobile/index.d.ts.map +1 -1
  44. package/dist/modules/mobile/index.js +40 -1
  45. package/dist/modules/mobile/index.js.map +1 -1
  46. package/dist/modules/mobile/services/mobile-cloud.service.d.ts +61 -0
  47. package/dist/modules/mobile/services/mobile-cloud.service.d.ts.map +1 -1
  48. package/dist/modules/mobile/services/mobile-cloud.service.js +15 -1
  49. package/dist/modules/mobile/services/mobile-cloud.service.js.map +1 -1
  50. package/dist/modules/mobile/services/ota-identity.service.d.ts +20 -0
  51. package/dist/modules/mobile/services/ota-identity.service.d.ts.map +1 -0
  52. package/dist/modules/mobile/services/ota-identity.service.js +169 -0
  53. package/dist/modules/mobile/services/ota-identity.service.js.map +1 -0
  54. package/dist/modules/mobile/services/ota-setup.service.d.ts +1 -0
  55. package/dist/modules/mobile/services/ota-setup.service.d.ts.map +1 -1
  56. package/dist/modules/mobile/services/ota-setup.service.js +268 -24
  57. package/dist/modules/mobile/services/ota-setup.service.js.map +1 -1
  58. package/dist/modules/scopes/commands/scope.command.d.ts +2 -0
  59. package/dist/modules/scopes/commands/scope.command.d.ts.map +1 -1
  60. package/dist/modules/scopes/commands/scope.command.js +125 -3
  61. package/dist/modules/scopes/commands/scope.command.js.map +1 -1
  62. package/dist/modules/scopes/index.d.ts.map +1 -1
  63. package/dist/modules/scopes/index.js +1 -0
  64. package/dist/modules/scopes/index.js.map +1 -1
  65. package/dist/modules/scopes/services/native-scope-inspection.service.d.ts +10 -0
  66. package/dist/modules/scopes/services/native-scope-inspection.service.d.ts.map +1 -0
  67. package/dist/modules/scopes/services/native-scope-inspection.service.js +75 -0
  68. package/dist/modules/scopes/services/native-scope-inspection.service.js.map +1 -0
  69. package/dist/modules/scopes/services/scope-native.service.d.ts +2 -0
  70. package/dist/modules/scopes/services/scope-native.service.d.ts.map +1 -1
  71. package/dist/modules/scopes/services/scope-native.service.js +43 -5
  72. package/dist/modules/scopes/services/scope-native.service.js.map +1 -1
  73. package/dist/modules/users/providers/npm-user.provider.d.ts +11 -0
  74. package/dist/modules/users/providers/npm-user.provider.d.ts.map +1 -1
  75. package/dist/modules/users/providers/npm-user.provider.js +16 -1
  76. package/dist/modules/users/providers/npm-user.provider.js.map +1 -1
  77. package/docs/assets/architecture.png +0 -0
  78. package/docs/assets/architecture.svg +123 -0
  79. package/docs/assets/backend-mobile.png +0 -0
  80. package/docs/assets/backend-mobile.svg +97 -0
  81. package/docs/assets/cleanup.png +0 -0
  82. package/docs/assets/cleanup.svg +104 -0
  83. package/docs/assets/setup-flow.png +0 -0
  84. package/docs/assets/setup-flow.svg +95 -0
  85. package/docs/assets/web-deployment.png +0 -0
  86. package/docs/assets/web-deployment.svg +72 -0
  87. package/package.json +21 -4
  88. package/vendor/QR-CODE-APACHE-2.0-LICENSE.txt +222 -0
  89. package/vendor/QR-CODE-MIT-LICENSE.txt +21 -0
  90. package/vendor/QR-CODE-NOTICE.txt +6 -0
  91. package/vendor/QRCode/QR8bitByte.js +22 -0
  92. package/vendor/QRCode/QRBitBuffer.js +38 -0
  93. package/vendor/QRCode/QRErrorCorrectLevel.js +7 -0
  94. package/vendor/QRCode/QRMaskPattern.js +10 -0
  95. package/vendor/QRCode/QRMath.js +44 -0
  96. package/vendor/QRCode/QRMode.js +6 -0
  97. package/vendor/QRCode/QRPolynomial.js +66 -0
  98. package/vendor/QRCode/QRRSBlock.js +298 -0
  99. package/vendor/QRCode/QRUtil.js +272 -0
  100. package/vendor/QRCode/index.js +462 -0
package/README.md CHANGED
@@ -1,778 +1,1526 @@
1
- # IndraQ CLI v2.7.1
1
+ # IndraQ CLI — developer guide (v2.7.9)
2
2
 
3
- IndraQ CLI helps our team set up, build and deploy web and mobile apps.
3
+ > **Mobile Jenkins safety policy:** IndraQ CLI **never creates, edits, replaces, repairs, or deletes** the shared mobile Jenkins Pipeline. Both `indraq mobile prebuild` and `indraq mobile build` check the existing manually managed `Mobile app Cli build` job **read-only**. If the job is missing, disabled, or has incorrect/missing parameters, the command stops; an administrator fixes Jenkins manually. Only an actual build request sends `POST /buildWithParameters` with the expected inputs.
4
4
 
5
- This guide uses simple steps. Start with the **Developer quick start**.
5
+ <div align="center">
6
+ <img src="docs/assets/indraq-logo.png" alt="IndraQ Innovations" width="240" />
6
7
 
7
- ---
8
+ # IndraQ CLI
8
9
 
9
- ## v2.7.1: Mobile prebuild fixes (quick guide)
10
+ **One command-line workspace for creating, connecting, building, deploying, and maintaining web and mobile projects.**
10
11
 
11
- `indraq project create` with **Backend + Mobile App** now offers to configure the mobile app immediately after the backend finishes. Answer **Yes** and select your mobile environment. You no longer need to run `indraq setup` solely to start the mobile half.
12
+ `v2.7.9` · `Node.js 22+` · `Windows / macOS / Linux` · `IndraQ Cloud` · `Jenkins` · `Docker` · `Expo / React Native`
13
+ </div>
12
14
 
13
- If a mobile Expo `app.json` contains commented entries (for example `// "./plugin"`) or trailing commas, IndraQ can now read it. Before rewriting it as normal JSON, IndraQ saves the original to `mobile/.indraq/backups/app.json.before-normalization`. Other config fields are kept. If the JSON is still invalid, IndraQ reports the filename **before** changing Jenkins or registering an OTA key.
15
+ > **Start here:** This guide assumes you have never used IndraQ CLI before. No familiarity with Jenkins, AWS, Docker registries, or deployment pipelines is required for the developer quick start. Screens and command names reflect the **v2.7.9 CLI source**. This README is intentionally a fresh user manual, not a historical changelog.
14
16
 
15
- For an existing combined project, run:
17
+ ## OTA activation reliability (v2.7.9)
16
18
 
17
- ```powershell
18
- cd mobile
19
- indraq mobile prebuild --env immortility
20
- indraq build mobile:dev --dry-run
21
- ```
19
+ Prebuild defaults to an anonymous, persistent per-installation ID. Optional saved-profile targeting can be enabled later with `indraq mobile identity configure`; it is not required for installation-based OTA.
22
20
 
23
- The existing `immortility` environment is a **Development** build environment, even though it uses the Jenkins **PROD** controller. A production build requires a separate **Production** mobile environment.
21
+ IndraQ now tracks each downloaded OTA update ID in local app storage. If the downloaded update is pending activation, the generated bootstrap **does not fetch it again**. It attempts an immediate native `expo-updates` reload once, then verifies success on a later JS launch when `Updates.updateId` matches the downloaded update ID. If native reload fails, the app retains the downloaded update and reports `activation_failed` with recent Expo native logs. It does **not** repeatedly reload or redownload the same release. The server may still receive lightweight manifest checks so a newer repair release can supersede a stuck one, but the same downloaded release is not fetched again.
24
22
 
25
- **Deployment:** This hotfix only updates the CLI. Keep the Cloud API v1.3.0 from the v2.7 release; there is no new database migration.
23
+ A native `ExpoUpdates.reload` rejection cannot be repaired solely by changing JavaScript: check the native module initialization (`UpdatesController`) if it persists. Emergency launch events are now reported as `emergency_launch`, not automatically interpreted as rollback. Verification uses `update_applied` rather than counting a download or a timer as a successful activation. The Jenkins Pipeline is never created or modified.
26
24
 
27
- ---
25
+ For a project created with an older CLI, run `indraq mobile prebuild` to regenerate the app-side bootstrap, review and commit the generated files, and distribute the updated JavaScript through a compatible OTA release or a fresh native build. The change is not retroactive to previously installed binaries.
28
26
 
29
- ## v2.7 foundation (quick guide)
27
+ ## Automatic device enrollment & targeting (v2.7.9)
30
28
 
31
- ### Backend + Mobile App
29
+ **No login-screen imports, no app email/phone assumptions, no hand-entered installation IDs.** Every installed production app reports a persistent, anonymous Installation ID. Developers can enroll named QA devices using a short-lived, one-time QR invitation generated by IndraQ Cloud.
32
30
 
33
- `indraq init` and `indraq project create` both offer **Backend + Mobile App**.
34
- The generated project contains `backend/` and `mobile/` folders.
31
+ ```mermaid
32
+ flowchart LR
33
+ A[Project owner: one-time mobile prebuild] --> B[Expo deep-link + OTA bootstrap]
34
+ B --> C[Install production APK]
35
+ D[ANY project member with VIEW] --> E[indraq mobile testers invite]
36
+ E --> F[One-time private QR]
37
+ F --> G[Phone scans QR]
38
+ G --> H[Tap Open App]
39
+ H --> I[App redeems invitation]
40
+ C --> I
41
+ I --> J[Named tester installation]
42
+ J --> K[Optional tester group]
43
+ K --> L[Send signed OTA to group]
44
+ L --> M[Only matching installed runtime receives update]
45
+ ```
35
46
 
36
- Run the same command from different folders:
47
+ The Project's IndraQ owner runs this **once** from the source checkout; it does not edit Jenkins:
37
48
 
38
49
  ```powershell
39
- cd C:\Projects\my-app\backend
40
- indraq prebuild # Docker/GitHub Packages/Jenkins/Route53/NPM
41
-
42
- cd ..\mobile
43
- indraq prebuild # Mobile Jenkins + OTA only
44
- indraq build mobile:dev # Development build
50
+ indraq mobile prebuild --env immortility --mode prod
51
+ indraq mobile build --env immortility --type expo --mode prod --output apk --profile fast
45
52
  ```
46
53
 
47
- From the project root, `indraq setup` walks through backend setup first, then mobile setup.
48
- `indraq mobile prebuild --env immortility` always explicitly selects mobile setup.
49
- Mobile build environments are separate from web deployment environments;
50
- a Development mobile environment cannot run a Production build.
54
+ Prebuild registers the native Expo deep-link scheme with IndraQ Cloud, generates `indraq-ota/bootstrap.js`, and creates the Expo Router `app/indraq-enroll.jsx` route **only if the route does not exist**. If the native scheme did not exist in the previously installed APK, install a new release APK first. Existing apps need the new generated bootstrap to receive QR enrollment deep links.
51
55
 
52
- ### Reuse an existing provider resource
56
+ **Every active IndraQ user with access to that project**, including normal users with VIEW permission, can generate a QR from any directory (not necessarily a clone of the app):
53
57
 
54
- When setting up a component, choose **Link existing** instead of **Create/reconcile**.
55
- You can link existing GitHub container packages, Jenkins deployment jobs, Route53 A records, and NPM proxy hosts.
56
- The CLI confirms the resource exists in the selected scope and saves the association.
57
- A linked resource is not silently overwritten; retain its existing configuration.
58
- Route53 record discovery needs manager/admin access; this is intentional.
58
+ ```powershell
59
+ indraq mobile testers invite
60
+ ```
59
61
 
60
- ### Safe permanent deletion
62
+ The command prompts for app (if multiple are accessible), device name, optional group and validity (5/15/30/60 minutes). It displays an actual QR in the terminal and saves an SVG to `.indraq/ota-enroll-<invitation-id>.svg` locally. Give it to the tester privately. The tester scans with their phone's camera, opens the enrollment webpage, and taps **Open App**. The IndraQ-enabled app redeems it once and registers the device without needing the app's login email or phone.
61
63
 
62
64
  ```powershell
63
- indraq project delete
65
+ indraq mobile testers list
66
+ indraq mobile testers installations
67
+ indraq mobile testers group create
68
+ indraq mobile testers revoke
69
+ indraq mobile send update
64
70
  ```
65
71
 
66
- Select only the external resources you want removed; all default to **KEEP**.
67
- The command now offers the exact provider scope when older projects have no scope link,
68
- with MANAGE access required to delete external resources. For old GitHub Packages
69
- scopes missing owner type, the CLI verifies the GitHub owner via GitHub's API
70
- instead of guessing. Deleting a container package removes **all tags**.
71
- Shared Jenkins mobile jobs, certificates, containers, and non-selected resources are not deleted.
72
- If a deletion fails, the Cloud project is kept for retry.
72
+ During **Send update**, pick **Tester groups**, **Named testers**, **Selected installations**, **Percentage rollout**, or **Everyone**. Group membership is checked against the live tester registry at each manifest request; revoking a tester prevents it from receiving future group-targeted releases. The Cloud API restricts release publishing to project WRITE permissions.
73
73
 
74
- **Upgrade:** Deploy Cloud API `1.3.0` before using CLI `2.7.1` deletion.
75
- Use `npm install`, `npm run build`, `npm test`, and `npm publish --dry-run`
76
- before publishing. Run the Cloud API build separately inside `cloud-api/`.
74
+ | Operation | Minimum project permission |
75
+ |---|---|
76
+ | Generate QR invitations and list own project's devices | **VIEW — all user roles** |
77
+ | Create QA/Beta tester groups or revoke enrollments | **WRITE** |
78
+ | Publish, promote, pause or roll back OTA releases | **WRITE** |
79
+
80
+ **Security:** The invitation is a one-time token (hashed at rest), expires in 5–60 minutes, and does not grant a Cloud user account or permission to publish. QR generation happens on the local computer using a bundled QR encoder—no outside QR service receives the invitation. Treat the SVG/link as confidential until redeemed. A tester device must already have registered its IndraQ-enabled app installation. Installation IDs are **device delivery identifiers**, not strong user authentication or verified proof of account identity.
81
+
82
+ **Platform scope:** Automated deep-link enrollment setup is currently implemented for **Expo** (including Expo Router). Existing React Native CLI projects can still receive installation-based and general OTA releases, but native QR deep links need a separate explicit Android/iOS link integration before enrollment will work. Live QR scanning, update application, and device testing must be verified before production rollout.
77
83
 
78
84
  ---
79
85
 
86
+ ## Automatic OTA audience identities (v2.7.9)
87
+
88
+ The primary workflow now uses **per-installation QR enrollment** and does **not** inspect or require each application's login users. The earlier profile adapter remains optional for legacy email/phone targeting: `indraq mobile prebuild` defaults to anonymous installation identity and reuses existing `indraq-ota/identity.json`. Only a developer deliberately running `indraq mobile identity configure` is asked to select saved profile keys.
89
+
90
+ ```powershell
91
+ indraq mobile prebuild --env immortility --mode prod
92
+ indraq mobile identity status
93
+ # Only if you change where the application saves user profiles:
94
+ indraq mobile identity configure
95
+ indraq mobile prebuild --env immortility --mode prod
96
+ ```
97
+
98
+ The adapter reads only the configured profile key, extracts `userId`, `username`, `email` and `phone` from conventional JSON fields or one-time custom paths, and reports changes as `identity_synced` while the app is foregrounded. The server clears prior identity fields on sign-out. Updates remain **startup-only** and will be checked on the next cold launch; no automatic reload during login or checkout. An installation ID is always available, even without an authenticated user.
99
+
100
+ **Important limitations:** There is no safe universal way to discover a custom app's logged-in identity. If the app stores only an opaque token, uses Redux-persist double-encoded JSON, keeps auth only in memory, or uses another storage backend, select installation-only mode until you add an explicit adapter or expose a readable, persisted profile. A configured storage key must contain a *profile*, not an access token or password. For SecureStore adapters, the native app needs `expo-secure-store`; prebuild installs it if missing, and then a new native build is required. For an already-installed app, publish the new identity bootstrap as an all-user OTA update first; **only subsequent updates** can reliably target that user's email/phone.
101
+
102
+ **Security:** Email/phone/user IDs in the current OTA request are client-reported routing attributes, **not verified authorization identities**. Treat the targeted rollout as convenience filtering, not protection for confidential content. Production-grade verified targeting requires a server-verified session/auth token integration.
80
103
 
81
- # Developer quick start — Web
104
+ **Jenkins protection remains absolute:** `mobile prebuild`, `mobile identity` and `mobile build` never create, replace, or edit the Jenkins Pipeline. They only validate the existing job and submit build parameters.
82
105
 
83
- ## 1. Login once
106
+ ## Live provider account checks and self-hosted OTA troubleshooting (v2.7.9)
107
+
108
+ A **Cloud scope assignment does not guarantee a working provider login**. Provider accounts can be deleted or changed directly in Jenkins, NPM, or AWS after IndraQ initially provisions them.
84
109
 
85
110
  ```powershell
86
- indraq login
111
+ indraq scope members # Read Cloud assignment + live provider account state
112
+ indraq scope sync # Inspect drift; explicitly choose accounts to repair
113
+ indraq scope add-user # Select an existing user and ANY additional scope
87
114
  ```
88
115
 
89
- Check your login:
116
+ The same IndraQ user can be granted access separately to Jenkins Immortility, Jenkins IndraQ, AWS accounts and NPM servers. Each scope has its own credentials and permissions. **No duplicate IndraQ Cloud account is needed.** `scope sync` never deletes external users or silently removes Cloud membership. It checks native-account existence and, for Jenkins/NPM, verifies stored provider credentials server-side without revealing passwords. External permission drift may still need manual review. On Jenkins, newly provisioned credentials are now login-tested before access is reported as successful. GitHub Packages scope access does **not** create a GitHub login or accept an organization invitation.
117
+
118
+ ### OTA update not received?
90
119
 
91
120
  ```powershell
92
- indraq whoami
121
+ indraq mobile doctor # Inspect OTA server, releases, native baseline, installations
122
+ indraq mobile metrics # Live IndraQ OTA telemetry
123
+ indraq mobile build --env immortility --type expo --mode prod --output apk
93
124
  ```
94
125
 
95
- Your login stays saved. You do not need to login before every build or deploy.
126
+ **Important:** Expo Development Client/debug builds do not run the startup-only IndraQ OTA check. Use a **release-mode APK** for a normal OTA test and ensure its OTA channel, runtime and native fingerprint match the targeted release. After the app launches online, its installation should appear in `indraq mobile metrics`.
127
+
128
+ For a release targeted to one logged-in account, your application's login code must call:
129
+
130
+ ```javascript
131
+ import { identifyIndraqOTA } from './indraq-ota/bootstrap';
132
+ await identifyIndraqOTA({ userId: account.id, email: account.email, username: account.username, phone: account.phone });
133
+ ```
134
+
135
+ Then **fully close and reopen** the installed release app. Target matching requires identity metadata from the app, not merely an existing logged-in session. IndraQ runs its own OTA server, so its releases and user counts are **not displayed in the Expo EAS Update dashboard**. Use `indraq mobile metrics` instead.
136
+
137
+ ---
138
+
139
+ ---
96
140
 
97
- Revoke the persistent Cloud session when you want to sign out.
141
+ ## Contents
142
+
143
+ 1. [What is IndraQ CLI?](#1-what-is-indraq-cli)
144
+ 2. [Why use it, and how does it work?](#2-why-use-it-and-how-does-it-work)
145
+ 3. [Install and sign in](#3-install-and-sign-in)
146
+ 4. [Project types and folder layouts](#4-project-types-and-folder-layouts)
147
+ 5. [Quick-start recipes](#5-quick-start-recipes)
148
+ 6. [Complete command map](#6-complete-command-map)
149
+ 7. [Command explanations and examples](#7-command-explanations-and-examples)
150
+ 8. [Web deployment: from code to server](#8-web-deployment-from-code-to-server)
151
+ 9. [Mobile builds and OTA updates](#9-mobile-builds-and-ota-updates)
152
+ 10. [Environments, scopes, and permissions](#10-environments-scopes-and-permissions)
153
+ 11. [Safe project deletion](#11-safe-project-deletion)
154
+ 12. [Configuration files and secrets](#12-configuration-files-and-secrets)
155
+ 13. [Troubleshooting](#13-troubleshooting)
156
+ 14. [FAQs, glossary, and developer notes](#14-faqs-glossary-and-developer-notes)
157
+
158
+ ---
98
159
 
99
- To logout and revoke the persistent Cloud session:
160
+ ## 1. What is IndraQ CLI?
161
+
162
+ **IndraQ CLI** is an internal command-line application maintained by **IndraQ Innovations**. It lets developers work with IndraQ's shared engineering infrastructure directly from a terminal (PowerShell, Command Prompt, Terminal, or a VS Code terminal).
163
+
164
+ Instead of manually opening multiple dashboards and repeating configuration work, you run a command such as:
100
165
 
101
166
  ```powershell
102
- indraq logout
167
+ indraq setup
103
168
  ```
104
169
 
170
+ The CLI asks friendly questions, checks your permissions, connects to **IndraQ Cloud**, and performs the selected setup or deployment tasks.
171
+
172
+ | Without a shared CLI | With IndraQ CLI |
173
+ |---|---|
174
+ | Manually create web deployment jobs | Use the guided setup / web prebuild workflow; mobile Jenkins remains manually managed |
175
+ | Manually identify container registry packages | Create or link a GitHub container package |
176
+ | Repeat deployment configuration per server | Save a project deployment topology |
177
+ | Configure DNS and reverse proxy separately | Select Route53 and NPM tasks when needed |
178
+ | Manually package mobile source for Jenkins | Run `indraq mobile build` |
179
+ | Manually manage JavaScript update releases | Publish controlled OTA updates |
180
+ | Guess which infrastructure belongs to a project | Review associations with `indraq project status` |
181
+
182
+ **What IndraQ CLI is not:** It is not your application framework, a replacement for Git, an iOS native build service, or a tool that grants permissions you do not already have.
183
+
184
+ ## 2. Why use it, and how does it work?
185
+
186
+ ### 2.1 The platform at a glance
187
+
188
+ ![IndraQ CLI architecture](docs/assets/architecture.svg)
189
+
190
+ **Follow the arrows:** a developer uses the CLI; the CLI checks IndraQ Cloud for identity, project configuration, and access; the platform then works with the selected infrastructure providers.
191
+
192
+ | Part | Plain-English purpose |
193
+ |---|---|
194
+ | **Your application folder** | Contains the code you write |
195
+ | **IndraQ CLI** | Guides you through actions and sends authorized requests |
196
+ | **IndraQ Cloud API** | Stores your project links, scope assignments, policies, audit events, and OTA information |
197
+ | **GitHub Packages (GHCR)** | Stores Docker container images for web deployment |
198
+ | **Jenkins** | Runs server deployment pipelines and Android build jobs |
199
+ | **Route53** | Points public domains to public server IPs |
200
+ | **Nginx Proxy Manager (NPM)** | Routes HTTPS requests to internal server IPs and ports |
201
+ | **IndraQ OTA + MinIO** | Distributes compatible signed JavaScript/asset updates to mobile apps |
202
+
203
+ > **Important:** “NPM” in infrastructure menus means **Nginx Proxy Manager**, not the `npm` command used to install JavaScript packages.
204
+
205
+ ### 2.2 Typical journey
206
+
207
+ ![Getting started flow](docs/assets/setup-flow.svg)
208
+
209
+ ```mermaid
210
+ flowchart TD
211
+ A[Open your project folder] --> B{Already linked to IndraQ Cloud?}
212
+ B -- No --> C[indraq project create or indraq init]
213
+ B -- Yes --> D[indraq project status]
214
+ C --> D
215
+ D --> E{What are you working on?}
216
+ E -- Web/backend --> F[indraq prebuild]
217
+ E -- Mobile --> G[indraq mobile prebuild]
218
+ E -- Both --> H[Configure backend then mobile]
219
+ F --> I[indraq deploy]
220
+ G --> J[indraq mobile build]
221
+ H --> I
222
+ H --> J
223
+ ```
224
+
225
+ There are **two separate ideas** to remember:
226
+
227
+ - **A project component** is *what* you are building: frontend, backend, mobile app, and so on.
228
+ - **An environment** is *where/how* it is deployed or built: a web server/environment or an admin-managed mobile build environment.
229
+
230
+ During new web project creation, developers see **one setup list** to select Dockerfile(s), GitHub Packages, Jenkins, Route53, and Nginx Proxy Manager. Only selected services are configured.
231
+
232
+ ### 2.3 What happens automatically versus manually?
233
+
234
+ | Operation | You choose | The CLI handles |
235
+ |---|---|---|
236
+ | First-time setup | Project type, environment, setup tasks | Links project and reconciles selected infrastructure |
237
+ | Reuse existing services | Link existing versus create/reconcile | Validates and records the selected association |
238
+ | Web deploy | Component(s), target(s), image tag | Build, push, Jenkins execution, and log streaming |
239
+ | Android build | Build server, Expo/native, dev/staging/prod, output/profile | Source snapshot, `.env` handling, Jenkins build, artifact links |
240
+ | OTA release | Environment, audience, update | Export, signing, upload, release controls |
241
+ | Project deletion | Which associated resources to delete or keep | Authorization checks and selected cleanup |
242
+
105
243
  ---
106
244
 
107
- ## 2. Open your project folder
245
+ ## 3. Install and sign in
246
+
247
+ ### 3.1 Requirements
248
+
249
+ | Item | Needed for | Notes |
250
+ |---|---|---|
251
+ | **Node.js 22+** | CLI | Verify with `node -v` |
252
+ | **npm** | Install CLI | Bundled with Node.js |
253
+ | **IndraQ Cloud account** | Login | An organization admin or manager must provide access |
254
+ | **Internet/network access** | Cloud, GitHub, Jenkins, AWS, NPM | You must be able to reach the services assigned to you |
255
+ | **Project source folder** | Build or deploy | Use VS Code or any editor |
256
+ | **Docker** | Web image build | Required on the machine performing local Docker image builds |
257
+ | **Expo / React Native dependencies** | Mobile builds | CLI checks the actual mobile framework and project |
258
+ | **Access to a configured Jenkins controller** | Web/mobile builds | Admin normally sets up provider scopes and mobile environments |
259
+
260
+ ### 3.2 Install the CLI
261
+
262
+ **Windows — PowerShell** (also works in macOS/Linux terminals):
108
263
 
109
264
  ```powershell
110
- cd C:\Projects\my-app
265
+ node -v
266
+ npm -v
267
+ npm install -g indraq_cli
268
+ indraq --version
269
+ indraq --help
111
270
  ```
112
271
 
113
- If the project is not in IndraQ yet:
272
+ The npm package name is `indraq_cli`; the terminal command is **`indraq`**.
273
+
274
+ To update an installation:
114
275
 
115
276
  ```powershell
116
- indraq project create
277
+ npm install -g indraq_cli@latest
278
+ indraq --version
117
279
  ```
118
280
 
119
- Choose your project type:
281
+ > For development of the **CLI itself**, clone or extract its source and run `npm install`, `npm run build`, and `npm test`. Those are not required for a normal global CLI installation.
120
282
 
121
- ```text
122
- Frontend
123
- Backend
124
- Frontend + Backend
125
- User Frontend + Admin Frontend + Backend
126
- Mobile App
283
+ ### 3.3 Log in once
284
+
285
+ ```powershell
286
+ indraq login
287
+ indraq whoami
127
288
  ```
128
289
 
129
- For web projects, choose the server/environment where the app will run.
290
+ The CLI retains a Cloud login session and refreshes it until logout or a security revocation. You do **not** need to log in before every deployment.
130
291
 
131
- Then IndraQ shows **one setup list**:
292
+ ```powershell
293
+ indraq logout
294
+ ```
132
295
 
133
- ```text
134
- What do you want to configure for this project now?
296
+ This revokes your persistent session and clears the local session credentials.
297
+
298
+ ### 3.4 First command to learn
135
299
 
136
- [x] Dockerfile(s)
137
- [x] GitHub Packages
138
- [x] Jenkins
139
- [ ] AWS Route53
140
- [ ] Nginx Proxy Manager
300
+ ```powershell
301
+ indraq setup
141
302
  ```
142
303
 
143
- Select what you want. IndraQ only starts the items you selected.
304
+ `setup` is the guided repair/onboarding flow for a project. If you already have application code, open its folder first and let the wizard register or link it.
144
305
 
145
- It does not keep asking:
306
+ ---
307
+
308
+ ## 4. Project types and folder layouts
309
+
310
+ The CLI supports the following presets:
311
+
312
+ | Project type | Cloud kind | Typical structure | Deployment path |
313
+ |---|---|---|---|
314
+ | Frontend | `frontend` | `./` | Web image → Jenkins |
315
+ | Backend | `backend` | `./` | Web image → Jenkins |
316
+ | Frontend + Backend | `fullstack` | `frontend/`, `backend/` | Each component → web pipeline |
317
+ | User Frontend + Admin Frontend + Backend | `multiweb` | `frontend/`, `admin/`, `backend/` | Three web components |
318
+ | Mobile App | `mobile` | `./` or designated app folder | Android Jenkins + OTA |
319
+ | **Backend + Mobile App** | `backend-mobile` | `backend/`, `mobile/` | Backend web pipeline + mobile Jenkins/OTA |
320
+
321
+ ### 4.1 Visual folder layouts
146
322
 
147
323
  ```text
148
- Would you like to configure it now?
324
+ WEB APP BACKEND + MOBILE APP
325
+ my-web-project/ my-combined-project/
326
+ ├── frontend/ ├── backend/
327
+ ├── backend/ │ ├── package.json
328
+ └── .indraq/ │ └── Dockerfile
329
+ ├── mobile/
330
+ │ ├── package.json
331
+ │ └── app.json
332
+ └── .indraq/
149
333
  ```
150
334
 
151
- for every item.
335
+ Paths above are examples. Single-component projects may use the root folder directly. Existing application files are preserved during `indraq project create`.
152
336
 
153
- ### What the setup items mean
337
+ ### 4.2 One project, two different build paths
154
338
 
155
- | Option | What it does |
156
- |---|---|
157
- | Dockerfile(s) | Creates missing Docker files |
158
- | GitHub Packages | Stores your Docker image at `ghcr.io` |
159
- | Jenkins | Creates/repairs the Jenkins deploy pipeline |
160
- | AWS Route53 | Creates/repairs DNS records |
161
- | Nginx Proxy Manager | Creates/repairs the reverse proxy and SSL |
339
+ ![Backend + Mobile App project](docs/assets/backend-mobile.svg)
340
+
341
+ For `backend-mobile`, the backend uses container infrastructure, while mobile uses its separate Android/OTA workflow. Both share the **same Cloud project association**. From `backend/`, web prebuild is used; from `mobile/`, mobile prebuild is used. At the project root, guided setup can configure both.
162
342
 
163
- For a new Jenkins deployment, select **GitHub Packages + Jenkins** together.
343
+ ### 4.3 When to use `init`, `project create`, or `project link`
344
+
345
+ ```mermaid
346
+ flowchart TD
347
+ Start{What do you have?}
348
+ Start -- No source code yet --> Init[indraq init]
349
+ Start -- Existing local source, new Cloud project --> Create[indraq project create]
350
+ Start -- Existing Cloud project, new computer/folder --> Link[indraq project link]
351
+ Start -- Unsure or repairing setup --> Setup[indraq setup]
352
+ ```
164
353
 
165
- Route53 and Nginx Proxy Manager run only when you select them.
354
+ | Command | Does it generate app source? | Best use |
355
+ |---|---|---|
356
+ | `indraq init` | **Yes**, on a new project | Start a new application from a supported template/generator |
357
+ | `indraq project create` | **No**; keeps your code | Register existing source and optionally configure infrastructure |
358
+ | `indraq project link` | No | Connect a folder to an accessible existing Cloud project |
359
+ | `indraq setup` | Uses existing state and prompts | Guided create/link/setup/repair |
360
+
361
+ **Safety:** `init` warns and requires a deliberate double confirmation before overwriting a populated folder that has not already been initialized by IndraQ.
166
362
 
167
363
  ---
168
364
 
169
- ## 3. Deploy
365
+ ## 5. Quick-start recipes
366
+
367
+ These are the shortest routes to a working project. Copy the example commands, replacing the paths/environment names with yours.
368
+
369
+ ### Recipe A — Existing web or backend project
170
370
 
171
371
  ```powershell
372
+ cd C:\Projects\my-backend
373
+ indraq login
374
+ indraq project create
375
+ indraq prebuild
376
+ indraq project status
172
377
  indraq deploy
173
378
  ```
174
379
 
175
- For a project with more than one part, choose what you want to deploy:
380
+ During project creation you can choose an environment and one setup checklist:
176
381
 
177
382
  ```text
178
- All components
179
- Frontend
180
- Backend
181
- Admin frontend
383
+ What do you want to configure now?
384
+ [x] Dockerfile(s)
385
+ [x] GitHub Packages
386
+ [x] Jenkins
387
+ [ ] AWS Route53
388
+ [ ] Nginx Proxy Manager
182
389
  ```
183
390
 
184
- Enter an image tag, for example:
391
+ Select only what you need. You can always run `indraq prebuild` later to add optional infrastructure.
185
392
 
186
- ```text
187
- latest
393
+ ### Recipe B — New project from scratch
394
+
395
+ ```powershell
396
+ mkdir C:\Projects\my-new-app
397
+ cd C:\Projects\my-new-app
398
+ indraq init
188
399
  ```
189
400
 
190
- or:
401
+ Choose a project type and answer the generator prompts. The CLI then links the project to Cloud and offers the relevant infrastructure setup. You can skip dependency installation with `indraq init --skip-install` if desired.
191
402
 
192
- ```text
193
- 1.3.0
403
+ ### Recipe C — Existing Expo or React Native app
404
+
405
+ ```powershell
406
+ cd C:\Projects\my-mobile-app
407
+ indraq project create
408
+ indraq mobile environment list
409
+ indraq mobile build --dry-run
410
+ indraq mobile build
194
411
  ```
195
412
 
196
- IndraQ will:
413
+ The guided build first asks which mobile/Jenkins environment to use, then the framework (Expo or React Native CLI), build type (Development, Staging, Production), output, and profile. **Any active mobile environment can run any Android build type** if its Jenkins server is properly configured.
197
414
 
198
- 1. Check the project setup.
199
- 2. Check Dockerfiles.
200
- 3. Build the Docker image.
201
- 4. Push the image to GitHub Packages.
202
- 5. Start the Jenkins build.
203
- 6. Show the Jenkins logs in the terminal.
204
- 7. Wait for Jenkins to finish.
415
+ **What your first Android build produces** depends on the framework and environment. For Expo Development it produces a **Development Client APK**. It does not produce a store-ready release APK.
205
416
 
206
- ### If Dockerfile is missing
417
+ ### Recipe D — Backend + Mobile App
207
418
 
208
- You do not need to stop and create it manually.
419
+ ```powershell
420
+ cd C:\Projects\my-combined-project
421
+ indraq project create
422
+ ```
209
423
 
210
- `indraq deploy` checks all selected components first.
424
+ Select **Backend + Mobile App** and the backend/mobile directories. The CLI can configure the backend first and then prompt to configure mobile Jenkins + OTA, within the same project creation/setup flow.
211
425
 
212
- If a Dockerfile is missing, it asks once:
426
+ Later, work from either subfolder:
213
427
 
214
- ```text
215
- Generate the missing Dockerfile(s) now? Yes
428
+ ```powershell
429
+ cd C:\Projects\my-combined-project\backend
430
+ indraq prebuild
431
+ indraq deploy
432
+
433
+ cd C:\Projects\my-combined-project\mobile
434
+ indraq prebuild --env <mobile-environment-slug>
435
+ indraq mobile build
216
436
  ```
217
437
 
218
- Then deploy continues.
438
+ ### Recipe E — Deploy the same web image to multiple servers
219
439
 
220
- ---
440
+ ```powershell
441
+ indraq project environments
442
+ indraq prebuild --all-targets
443
+ indraq deploy --all
444
+ ```
221
445
 
222
- # Easy guided setup
446
+ The same immutable image digest is deployed to all selected targets (provided they share the correct logical GitHub Packages image). This is not a separate rebuild per server.
223
447
 
224
- If you are not sure which command to use, run:
448
+ ### Recipe F — Make an OTA update after a successful native build
225
449
 
226
450
  ```powershell
227
- indraq setup
451
+ indraq mobile send update --app "My App" --env <mobile-environment-slug>
452
+ indraq mobile metrics --app "My App"
228
453
  ```
229
454
 
230
- IndraQ will guide you through:
455
+ Test the update with a limited audience before running:
231
456
 
232
- 1. Login.
233
- 2. Project create/link.
234
- 3. Environment selection.
235
- 4. One setup list.
236
- 5. Only the items you select.
457
+ ```powershell
458
+ indraq mobile release update --app "My App"
459
+ ```
237
460
 
238
- Use this command for first-time setup or repair.
461
+ OTA is for compatible JavaScript and asset changes, **not** changes requiring a new native binary.
239
462
 
240
463
  ---
241
464
 
242
- # Prebuild
465
+ ## 6. Complete command map
466
+
467
+ The command list below is based on the **actual v2.7.9 command registration**, including normal commands, administrative commands, and compatibility aliases.
468
+
469
+ ### 6.1 Navigation map
470
+
471
+ ```mermaid
472
+ mindmap
473
+ root((indraq))
474
+ Start
475
+ help
476
+ doctor
477
+ login/logout
478
+ setup
479
+ configure
480
+ Projects
481
+ init
482
+ project
483
+ access
484
+ Web
485
+ prebuild
486
+ deploy
487
+ deployment
488
+ dockerfile
489
+ Mobile
490
+ mobile environment
491
+ mobile prebuild
492
+ build mobile:dev/staging/prod
493
+ mobile OTA
494
+ Infrastructure
495
+ scope
496
+ environment
497
+ jenkins
498
+ dns
499
+ proxy
500
+ iam
501
+ healthcheck
502
+ Organization
503
+ user
504
+ password
505
+ logs
506
+ ```
507
+
508
+ ### 6.2 Start, help, authentication, and configuration
509
+
510
+ | Command | What it does |
511
+ |---|---|
512
+ | `indraq --help` | Show CLI overview and full command reference |
513
+ | `indraq --version` / `indraq -V` | Show installed CLI version |
514
+ | `indraq help [topic]` | Show focused help; topics include `project`, `mobile`, `scope`, `aws`, and more |
515
+ | `indraq doctor` | Diagnose Node.js, npm and CLI command-resolution problems |
516
+ | `indraq login` | Sign in to IndraQ Cloud |
517
+ | `indraq logout` | Revoke and clear the local persistent session |
518
+ | `indraq whoami` | Show the authenticated Cloud identity |
519
+ | `indraq password reset` | Recover/reset Cloud or supported provider passwords using email OTP |
520
+ | `indraq setup` | Guided project onboarding and infrastructure repair |
521
+ | `indraq configure` | Open configuration home: scopes, project infrastructure, mobile settings |
522
+
523
+ ### 6.3 Projects and membership
524
+
525
+ | Command | What it does |
526
+ |---|---|
527
+ | `indraq init [directory]` | Scaffold a new web/mobile project and link Cloud project |
528
+ | `indraq project create [name]` | Register current source as a Cloud project; optional setup |
529
+ | `indraq project list` | List projects visible to you |
530
+ | `indraq project link` | Associate current folder with an existing Cloud project |
531
+ | `indraq project sync` | Migrate old local project metadata to a Cloud project reference |
532
+ | `indraq project status` | Display components, environments and resource associations |
533
+ | `indraq project environments` | Choose deployment targets for a project |
534
+ | `indraq project targets` | Alias for `project environments` |
535
+ | `indraq project scopes --env <name>` | Choose provider scopes for the specified environment |
536
+ | `indraq project add user` | Add a user to a project |
537
+ | `indraq project delete user` | Remove a user from a project |
538
+ | `indraq project rename [name]` | Rename a project |
539
+ | `indraq project archive` | Archive a project to block deployment mutations |
540
+ | `indraq project restore` | Restore an archived project |
541
+ | `indraq project delete` | Delete Cloud project and optionally selected associated external resources |
542
+ | `indraq access add user` | Grant access to selected AWS/NPM/Jenkins project resources |
543
+ | `indraq access delete user` | Revoke access to selected project resources |
544
+
545
+ ### 6.4 Web setup and deployment
546
+
547
+ | Command | What it does |
548
+ |---|---|
549
+ | `indraq dockerfile create` | Generate missing Docker artifacts for an existing application |
550
+ | `indraq prebuild` | Select and configure permitted infrastructure (mobile Jenkins is read-only) |
551
+ | `indraq prebuild --env <name>` | Prebuild a specific deployment environment (or mobile environment in mobile context) |
552
+ | `indraq prebuild --all-targets` | Configure all project web deployment targets |
553
+ | `indraq prebuild --required-only` | Only GitHub Packages and Jenkins for a web project |
554
+ | `indraq deploy` | Build, push, and deploy chosen web component(s) |
555
+ | `indraq deploy --env <name>` | Deploy one selected environment |
556
+ | `indraq deploy --all` | Deploy the same image digest to all configured targets |
557
+ | `indraq deploy --select-scopes` | Review/change provider scope bindings as part of deployment |
558
+ | `indraq deploy build` | Compatibility subcommand for build/push/deploy |
559
+ | `indraq deploy configure` | Open main configuration menu |
560
+ | `indraq deployment create` | Reconcile deployment infrastructure (prebuild alias) |
561
+ | `indraq deployment run` | Run a web deployment |
562
+ | `indraq deploy:configure` | Alias for `indraq configure` |
563
+ | `indraq deploy:dev` | Target an environment named dev/development, if configured |
564
+ | `indraq deploy:prod` | Target an environment named prod/production, if configured |
565
+
566
+ ### 6.5 Mobile environments, Android build, and OTA
567
+
568
+ | Command | What it does |
569
+ |---|---|
570
+ | `indraq mobile environment list` | Show active mobile environments |
571
+ | `indraq mobile environment create` | Create admin-managed mobile environment |
572
+ | `indraq mobile environment update` | Update a mobile environment |
573
+ | `indraq mobile environment delete` | Disable a mobile environment |
574
+ | `indraq mobile env ...` | Alias for `indraq mobile environment ...` |
575
+ | `indraq mobile prebuild --env <name> --mode <dev|staging|prod>` | Validate existing mobile Jenkins pipeline (read-only) and configure OTA runtime |
576
+ | **`indraq mobile build`** | **Guided build: choose Jenkins environment first, Expo/React Native, Development/Staging/Production, output and profile** |
577
+ | `indraq mobile build --env immortility --mode prod --type expo --output aab --profile clean` | Run with explicit selections instead of prompts (still confirms before build) |
578
+ | `indraq build mobile:dev` | Android Development build |
579
+ | `indraq build mobile:development` | Alias for development build |
580
+ | `indraq build mobile:staging` | Android Staging build |
581
+ | `indraq build mobile:prod` | Android Production build |
582
+ | `indraq build mobile:production` | Alias for production build |
583
+ | `indraq mobile testers invite` | All project users with VIEW access can generate one-time QR invites (any directory) |
584
+ | `indraq mobile testers list` | Show testers and groups |
585
+ | `indraq mobile testers installations` | Show installations registered with OTA |
586
+ | `indraq mobile testers group create` | Create a named tester group (WRITE) |
587
+ | `indraq mobile testers revoke` | Revoke enrolled tester access (WRITE) |
588
+ | `indraq mobile send update` | Export an OTA update; select groups, named testers, installations, percentage or everyone |
589
+ | `indraq mobile release update` | Promote a tested immutable OTA release to everyone |
590
+ | `indraq mobile pause` | Pause a selected OTA release |
591
+ | `indraq mobile rollback` | Republish previous known-good OTA assets |
592
+ | `indraq mobile metrics` | Show OTA release statistics and adoption |
593
+ | `indraq mobile doctor` | Diagnose update server health, OTA compatibility, registered installations and release targeting |
594
+
595
+ **Preferred:** `indraq mobile build`. Legacy shortcuts such as `indraq build mobile:prod` remain supported. `indraq mobile build:prod` is **not** a command; use `indraq mobile build --mode prod`.
596
+
597
+ ### 6.6 Organization environments and provider scopes
598
+
599
+ | Command | What it does |
600
+ |---|---|
601
+ | `indraq environment create` | Create a shared web environment with public/private IPs (admin) |
602
+ | `indraq environment list` | List shared web environments |
603
+ | `indraq environment update [name]` | Update an environment (admin) |
604
+ | `indraq environment delete [name]` | Delete unused environment (admin) |
605
+ | `indraq scope list` | List only provider scopes assigned to you |
606
+ | `indraq scope describe [nameOrId]` | Inspect scope metadata without exposing secrets |
607
+ | `indraq scope create [provider]` | Create scope for AWS/NPM/Jenkins/GitHub Packages (admin) |
608
+ | `indraq scope aws-zone [nameOrId]` | Set AWS scope default hosted zone (admin) |
609
+ | `indraq scope delete [nameOrId]` | Delete unused provider scope (admin) |
610
+ | `indraq scope members` | List Cloud members and verify live Jenkins/NPM/AWS identities and login status |
611
+ | `indraq scope sync` | Inspect missing/stale provider users, and optionally repair identities or credentials |
612
+ | `indraq scope add-user` | Add scope membership and native identity |
613
+ | `indraq scope remove-user` | Remove scope membership and associated native identity |
614
+ | `indraq scope default [provider]` | Set your personal default scope for a provider |
615
+ | `indraq scope audit` | Review scope change history |
616
+ | `indraq scope credentials` | Display your own managed AWS CLI credential |
617
+ | `indraq scope rotate-key` | Rotate your own AWS access key |
618
+ | `indraq scope rotate-password` | Rotate your NPM/Jenkins password |
619
+
620
+ ### 6.7 Organization users and audit
621
+
622
+ | Command | What it does |
623
+ |---|---|
624
+ | `indraq user list` | List Cloud users (manager/admin) |
625
+ | `indraq user scopes [email]` | List your own or manageable user's scopes |
626
+ | `indraq user create [username]` | Create Cloud user and assign selected scopes |
627
+ | `indraq user update [username]` | Update user profile/role within permissions |
628
+ | `indraq user delete [username]` | Clean up manageable native identities and delete Cloud user |
629
+ | `indraq logs` | View organization audit logs (manager/admin) |
630
+
631
+ ### 6.8 Jenkins administration and direct builds
632
+
633
+ | Command | What it does |
634
+ |---|---|
635
+ | `indraq jenkins pipelines` | List visible runnable Jenkins jobs |
636
+ | `indraq jenkins build [job]` | Run selected pipeline; prompt for its parameters; stream logs |
637
+ | `indraq jenkins run [job]` | Alias for `jenkins build` |
638
+ | `indraq jenkins pipeline:run [job]` | Compatibility alias |
639
+ | `indraq jenkins deployments` | List Jenkins deployment jobs |
640
+ | `indraq jenkins create-deployment` | Start bootstrap CREATE-DEPLOYMENT pipeline |
641
+ | `indraq jenkins deployment:update [job]` | Reconcile/update a Jenkins deployment job |
642
+ | `indraq jenkins deployment:delete [job]` | Delete a selected Jenkins deployment job |
643
+ | `indraq jenkins users` | List Jenkins users |
644
+ | `indraq jenkins user:update [username]` | Update a Jenkins user |
645
+ | `indraq jenkins user:delete [username]` | Delete a Jenkins user |
646
+
647
+ ### 6.9 AWS, Route53, health checks and proxy administration
648
+
649
+ | Command | What it does |
650
+ |---|---|
651
+ | `indraq iam users` | List AWS IAM users |
652
+ | `indraq iam user:create [username]` | Create IAM CLI user/access key |
653
+ | `indraq iam user:update [username]` | Update IAM managed policies |
654
+ | `indraq iam user:delete [username]` | Delete IAM identity and supported dependencies |
655
+ | `indraq iam credentials [username]` | Show authorized stored AWS IAM credentials |
656
+ | `indraq iam access-key rotate [username]` | Rotate managed AWS access key |
657
+ | `indraq dns zones` | List Route53 hosted zones |
658
+ | `indraq dns records --zone <id>` | List record sets in a zone |
659
+ | `indraq dns create [record]` | Create Route53 A record |
660
+ | `indraq dns update [record]` | Create/update A record via UPSERT |
661
+ | `indraq dns delete [record]` | Delete selected Route53 record set(s) |
662
+ | `indraq healthcheck list` | List Route53 health checks |
663
+ | `indraq healthcheck create` | Create health check (admin) |
664
+ | `indraq healthcheck delete [id]` | Delete health check (admin) |
665
+ | `indraq proxy list` | List Nginx Proxy Manager proxy hosts |
666
+ | `indraq proxy create [domain]` | Create proxy host |
667
+ | `indraq proxy update [domain]` | Update proxy host |
668
+ | `indraq proxy delete [domain]` | Delete proxy host |
669
+ | `indraq npm-user list` | List NPM users |
670
+ | `indraq npm-user create` | Create NPM user |
671
+ | `indraq npm-user update [identity]` | Update NPM user |
672
+ | `indraq npm-user delete [identity]` | Delete NPM user |
673
+
674
+ ### 6.10 Compatibility / legacy aliases
675
+
676
+ These commands remain registered for older workflows. **New users should prefer the commands already listed above.**
677
+
678
+ | Legacy command | Use instead |
679
+ |---|---|
680
+ | `indraq cloud login`, `cloud logout`, `cloud whoami` | `indraq login`, `logout`, `whoami` |
681
+ | `indraq server create`, `indraq server list` | `indraq environment create/list` |
682
+ | `indraq provider configure`, `provider list`, `provider describe`, `provider default` | `indraq scope ...` |
683
+ | `indraq credentials configure`, `credentials list`, `credentials sync`, `credentials restore` | Manage scopes and credentials using supported scope flows |
684
+
685
+ ---
686
+
687
+ ## 7. Command explanations and examples
688
+
689
+ The earlier command map answers **“which command exists?”** This chapter answers **“when and how should I use it?”**
243
690
 
244
- Use prebuild when you want to add or repair project services:
691
+ ### 7.1 `login`, `logout`, `whoami`, `password reset`
245
692
 
246
693
  ```powershell
247
- indraq prebuild
694
+ indraq login
695
+ indraq whoami
696
+ indraq password reset
697
+ indraq logout
248
698
  ```
249
699
 
250
- You get one list:
700
+ - `login`: interactive Cloud credentials; persistent Cloud session.
701
+ - `whoami`: check identity and role before using protected resources.
702
+ - `password reset`: supports email-OTP reset for Cloud, supported provider credentials, or all password-based targets. Use `indraq password reset --help` for flags.
703
+ - `logout`: revoke the current session on the server and locally.
251
704
 
252
- ```text
253
- What should prebuild configure?
705
+ ### 7.2 `init`
254
706
 
255
- [ ] GitHub Packages
256
- [ ] Jenkins
257
- [ ] AWS Route53
258
- [ ] Nginx Proxy Manager
707
+ ```powershell
708
+ indraq init
709
+ indraq init C:\Projects\my-app
710
+ indraq init --skip-install
259
711
  ```
260
712
 
261
- Only selected items run.
713
+ Use **`init`** for a brand-new application. It can generate web project structure or use an official Expo/React Native generator. You may be asked about framework, Node version, backend port, optional integrations, or database settings depending on the project type.
714
+
715
+ `init` creates/links project metadata; it does **not** guarantee that optional DNS/proxy infrastructure is active unless you select/configure it. For a new mobile-only generator, follow the on-screen instruction to run mobile prebuild afterward.
262
716
 
263
- For one environment:
717
+ ### 7.3 `project create`, `project link`, `project status`
264
718
 
265
719
  ```powershell
266
- indraq prebuild --env production
720
+ indraq project create
721
+ indraq project create "My API" --kind backend --port 8000
722
+ indraq project list
723
+ indraq project link
724
+ indraq project status
267
725
  ```
268
726
 
269
- For all project environments:
727
+ `project create` keeps existing source and creates a Cloud record for its components. Supported `--kind` values include `frontend`, `backend`, `fullstack`, `multiweb`, `mobile`, and `backend-mobile`. The wizard can choose deployment environments and the setup tasks to perform now.
728
+
729
+ `project link` connects a new local checkout to an accessible existing project instead of creating a duplicate Cloud project. `project status` is your read-only place to inspect what is registered.
730
+
731
+ ### 7.4 `project environments` and `project scopes`
270
732
 
271
733
  ```powershell
272
- indraq prebuild --all-targets
734
+ indraq project environments
735
+ indraq project scopes --env production
736
+ indraq scope list
273
737
  ```
274
738
 
275
- GitHub Packages + Jenkins only:
739
+ - **Project environments** choose the actual web target servers your project is allowed to deploy to.
740
+ - **Project scopes** choose which AWS, GitHub Packages, Jenkins DEV/PROD, and NPM accounts the target environment uses.
741
+ - **Scope list** shows only resources you are assigned to.
742
+
743
+ A shared environment name is not necessarily the Jenkins stage: an admin can explicitly map the environment to Jenkins DEV or PROD.
744
+
745
+ ### 7.5 `setup` versus `prebuild`
746
+
747
+ | `indraq setup` | `indraq prebuild` |
748
+ |---|---|
749
+ | Full guided onboarding / repair | Infrastructure configuration for an existing linked project |
750
+ | Can help with login and project linking | Assumes the project is registered |
751
+ | Can include Dockerfile generation | Web checklist focuses on GHCR/Jenkins/Route53/NPM |
752
+ | At combined-project root, can run backend and mobile setup | Detects the current component context |
753
+
754
+ **Web prebuild setup checklist:** GitHub Packages + Jenkins are required for standard web deployment; Route53/NPM are optional. Link existing resources when appropriate rather than creating duplicates.
276
755
 
277
756
  ```powershell
757
+ indraq prebuild
758
+ indraq prebuild --env my-server
759
+ indraq prebuild --all-targets
278
760
  indraq prebuild --required-only
279
761
  ```
280
762
 
281
- ---
763
+ `--required-only` means **skip optional DNS and proxy**, not “skip access checks”.
764
+
765
+ ### 7.6 `deploy`
766
+
767
+ ```powershell
768
+ indraq deploy
769
+ indraq deploy --env production
770
+ indraq deploy --all
771
+ indraq deploy --env production --select-scopes
772
+ ```
282
773
 
283
- # Multiple servers
774
+ `deploy` is the web path: choose component(s), validate/generate missing Dockerfiles when offered, build Docker images, push them to GitHub Packages, and run Jenkins deployments. It streams the Jenkins console and waits for the result unless you use an independently configured direct Jenkins command with `--no-wait`.
284
775
 
285
- A project can run on more than one server.
776
+ **`--env` does not choose a `.env` file.** It selects the IndraQ infrastructure environment.
286
777
 
287
- Choose the servers:
778
+ ### 7.7 `dockerfile create`
288
779
 
289
780
  ```powershell
290
- indraq project environments
781
+ indraq dockerfile create
291
782
  ```
292
783
 
293
- Example:
784
+ Generates Docker artifacts for a supported application component when they are missing. Review the generated Dockerfile and `.dockerignore` before production deployment. Existing files are preserved where the generator is designed to avoid overwriting them.
785
+
786
+ ### 7.8 `configure`
787
+
788
+ ```powershell
789
+ indraq configure
790
+ ```
791
+
792
+ This is the interactive configuration home. It includes personal provider scope defaults, project scope bindings, infrastructure reconciliation, and **Mobile App settings**.
294
793
 
295
794
  ```text
296
- prod-primary
297
- prod-backup
795
+ indraq configure
796
+ ├─ Choose default provider scope
797
+ ├─ Choose project provider scopes
798
+ ├─ Reconcile project infrastructure
799
+ └─ Mobile App settings
800
+ ├─ App name / Expo or React Native CLI
801
+ ├─ Version + Android versionCode
802
+ └─ Build output and profile for dev / staging / prod
298
803
  ```
299
804
 
300
- Deploy one server:
805
+ For mobile version management, automatic increment toggles are independent: app version and Android versionCode can each be ON or OFF. They advance only after successful native Jenkins builds.
806
+
807
+ ### 7.9 `jenkins pipelines` and `jenkins build`
301
808
 
302
809
  ```powershell
303
- indraq deploy --env prod-primary
810
+ indraq jenkins pipelines --stage dev
811
+ indraq jenkins build --stage dev
812
+ indraq jenkins build "My Pipeline" --stage prod
304
813
  ```
305
814
 
306
- Deploy all configured servers:
815
+ Use these for **direct Jenkins job execution**, not automatic web project deployment. The CLI lists jobs visible to your provider identity and prompts for their declared parameters. `indraq jenkins build ... --no-wait` queues the job without following it to completion.
816
+
817
+ ### 7.10 `scope`, `user`, `access` and `logs`
307
818
 
308
819
  ```powershell
309
- indraq deploy --all
820
+ indraq scope list
821
+ indraq scope describe
822
+ indraq scope default github-packages
823
+ indraq user list
824
+ indraq user scopes
825
+ indraq access add user
826
+ indraq logs
310
827
  ```
311
828
 
312
- IndraQ builds the image once and sends the **same exact image** to every selected Jenkins server.
829
+ - `scope`: identify which organization provider account you are allowed to use.
830
+ - `user`: manage Cloud identities and their scope assignments (role-dependent).
831
+ - `access`: grant/revoke project-specific AWS/NPM/Jenkins resource access with audit records.
832
+ - `logs`: inspect organizational audit records if permitted.
313
833
 
314
- ---
834
+ ### 7.11 `environment`, `dns`, `proxy`, `iam`, `healthcheck`, `npm-user`
315
835
 
316
- # Jenkins build reliability
836
+ These are **infrastructure/admin tools**. Use the guided project workflow for routine deployments. Direct commands are available for authorized diagnostics and management.
317
837
 
318
- IndraQ v2.5.0 is safer when Jenkins or the reverse proxy is slow.
838
+ | Family | Example | Typical reason |
839
+ |---|---|---|
840
+ | Environment | `indraq environment list` | See public/internal IP targets |
841
+ | DNS | `indraq dns records --zone Z123` | Check an A record |
842
+ | Proxy | `indraq proxy list` | Inspect reverse proxy and SSL routing |
843
+ | AWS IAM | `indraq iam users` | Manage provider-native IAM users |
844
+ | Health check | `indraq healthcheck list` | Review Route53 health checks |
845
+ | NPM users | `indraq npm-user list` | Review reverse-proxy user accounts |
319
846
 
320
- If Jenkins accepts the deploy request but the CLI temporarily gets a timeout or 502, IndraQ does **not** automatically send the same deploy again.
847
+ All direct commands still enforce the relevant IndraQ/project/provider permissions.
321
848
 
322
- It tries to find the Jenkins build that was already started and continues following that build.
849
+ ---
323
850
 
324
- If IndraQ cannot safely find the build, it tells you to check Jenkins before retrying. This avoids duplicate deployments.
851
+ ## 8. Web deployment: from code to server
325
852
 
326
- ---
853
+ ### 8.1 Where the application goes
854
+
855
+ ![Web deploy pipeline](docs/assets/web-deployment.svg)
327
856
 
328
- # GitHub Packages
857
+ ```mermaid
858
+ sequenceDiagram
859
+ actor Developer
860
+ participant CLI as IndraQ CLI
861
+ participant GHCR as GitHub Packages
862
+ participant JA as Jenkins A
863
+ participant JB as Jenkins B
864
+ Developer->>CLI: indraq deploy --all
865
+ CLI->>CLI: Verify project, targets, Dockerfiles, scopes
866
+ CLI->>GHCR: Build + push image once
867
+ GHCR-->>CLI: Immutable image digest
868
+ CLI->>JA: Deploy exact digest
869
+ JA-->>CLI: Build status + logs
870
+ CLI->>JB: Deploy same digest
871
+ JB-->>CLI: Build status + logs
872
+ CLI-->>Developer: Summary
873
+ ```
329
874
 
330
- The CLI now shows the name:
875
+ For multiple servers, the CLI builds **once** and submits the **same image digest** to each configured target sequentially. If a target fails, the command stops and reports it.
876
+
877
+ ### 8.2 What each service contributes
331
878
 
332
879
  ```text
333
- GitHub Packages
880
+ Code -> Docker image -> GitHub Packages -> Jenkins -> Running container
881
+ |
882
+ Public DNS (Route53) ---> Public IP ---> NPM proxy ---> Internal IP:port
334
883
  ```
335
884
 
336
- Internally the Docker registry is still:
885
+ - **Docker image:** packaged application and runtime.
886
+ - **GitHub Packages:** stored image, available by tag and immutable digest.
887
+ - **Jenkins:** deploys the requested image on the selected server.
888
+ - **Route53:** makes your domain point at a public IP.
889
+ - **NPM:** forwards HTTPS to the correct internal server IP and port.
890
+
891
+ ### 8.3 Public versus private IPs
337
892
 
338
893
  ```text
339
- ghcr.io
894
+ example.com
895
+ |
896
+ v
897
+ Route53 A record ──> External/Public IPv4
898
+ |
899
+ v
900
+ Nginx Proxy Manager
901
+ |
902
+ v
903
+ Internal/Private IPv4:PORT
904
+ |
905
+ v
906
+ App container
340
907
  ```
341
908
 
342
- Developers do not need to remember the name `GHCR`.
909
+ **Do not swap them:** Route53 receives the environment's *external/public IPv4*, while NPM uses its *internal/private IPv4* as the upstream.
343
910
 
344
- ---
911
+ ### 8.4 Link existing versus create/reconcile
345
912
 
346
- # Web environment IPs
913
+ During **web** project prebuild, the CLI can offer both options for existing GHCR packages, Jenkins jobs, Route53 records, and NPM proxy hosts. **The shared mobile Jenkins job is always managed manually; IndraQ will not create it or offer a create option.** Linking means **record the relationship without recreating or intentionally modifying the external resource**; creating/reconciling may create or update its configuration.
347
914
 
348
- Admins create web environments with two IPs:
915
+ Example:
349
916
 
350
917
  ```text
351
- External/Public IPv4
352
- Internal/Private IPv4
353
- ```
354
-
355
- They are used like this:
918
+ GitHub Packages for backend:
919
+ ○ Create/reconcile package association
920
+ ● Link existing container package (do not modify)
356
921
 
357
- ```text
358
- AWS Route53 -> External/Public IPv4
359
- Nginx Proxy Manager -> Internal/Private IPv4
922
+ Choose package: barakah-backend
923
+ ✓ Linked ghcr.io/organization/barakah-backend
360
924
  ```
361
925
 
362
- Developers normally only select the environment name.
926
+ A recorded association does not prove that the selected image tag exists or that a future deployment will succeed. The deployment still needs valid credentials and a usable image.
363
927
 
364
928
  ---
365
929
 
366
- # Audit reasons
367
-
368
- Normal creation/setup should stay quick.
369
-
370
- IndraQ does **not** ask for an audit reason when creating or setting up new items such as:
930
+ ## 9. Mobile builds and OTA updates
371
931
 
372
- - project creation
373
- - environment creation
374
- - provider scope creation
375
- - mobile environment creation
376
- - automatic setup/prebuild links
932
+ ### 9.1 Two separate workflows
377
933
 
378
- IndraQ writes a safe automatic reason for those actions.
934
+ ```mermaid
935
+ flowchart LR
936
+ App[Mobile source] --> Native{Did native dependencies or native config change?}
937
+ Native -- Yes --> J[Android Jenkins build]
938
+ J --> Baseline[Record compatible native baseline]
939
+ Native -- No, JS/assets only --> OTA[Create signed OTA update]
940
+ Baseline --> OTA
941
+ OTA --> Test[Target a test audience]
942
+ Test --> Release[Promote same tested release]
943
+ Release --> Device[Eligible installed apps on cold start]
944
+ ```
379
945
 
380
- IndraQ asks for a reason when you change or delete existing data, for example:
946
+ **Native build:** produces an APK or AAB through Jenkins. **OTA:** sends compatible JavaScript and asset changes without producing another APK/AAB. The CLI blocks OTA when the source's native fingerprint does not match a recorded successful native build.
381
947
 
382
- - update/delete an environment
383
- - update/delete a user
384
- - rename/delete a project
385
- - archive/restore a project
386
- - remove access
387
- - rotate credentials
948
+ ### 9.2 Supported Android build matrix
388
949
 
389
- ---
950
+ | Project type | Development | Staging | Production |
951
+ |---|---|---|---|
952
+ | **Expo** | Development Client APK | Release APK or Release AAB | Release APK or Release AAB |
953
+ | **React Native CLI** | Debug APK | Release APK or Release AAB | Release APK or Release AAB |
390
954
 
391
- # Mobile quick start
955
+ **Build profiles:**
392
956
 
393
- IndraQ supports:
957
+ | Profile | Meaning |
958
+ |---|---|
959
+ | `FAST` | Fresh source, reuse shared npm/Gradle caches |
960
+ | `CLEAN` | Clean project build state first |
961
+ | `FULL_RESET` | Reset project/Jenkins build caches for a deeper clean |
394
962
 
395
- - Expo
396
- - React Native CLI
963
+ ### 9.3 Create a reusable mobile build environment
397
964
 
398
- Create a new mobile project:
965
+ **Mobile build environment = which Jenkins controller to use.** It does **not** fix Development/Staging/Production. One server can compile any Android build mode; you choose the mode for each build.
399
966
 
400
967
  ```powershell
401
- indraq init
968
+ indraq mobile environment list
969
+ # Administrator only (when adding a new build environment):
970
+ indraq mobile environment create
402
971
  ```
403
972
 
404
- Choose:
973
+ On creation, the admin chooses a name, Jenkins DEV/PROD controller, and OTA channel. The legacy Cloud database retains a `build_type` field for compatibility, but **v2.7.9 ignores it when selecting a Jenkins build environment**. Existing `Immortility` works for all three modes. Normal developers still need permission to use the selected Jenkins provider scope.
405
974
 
406
- ```text
407
- Mobile App
408
- ```
975
+ ### 9.4 Guided Android builds (recommended)
409
976
 
410
- Then choose:
977
+ ```powershell
978
+ cd C:\Projects\my-mobile-app
979
+ indraq mobile build
980
+ ```
981
+
982
+ ```mermaid
983
+ flowchart TD
984
+ A[indraq mobile build] --> B[Choose mobile environment / Jenkins server]
985
+ B --> C{App type?}
986
+ C --> D[Expo]
987
+ C --> E[React Native CLI]
988
+ D --> F{Build type?}
989
+ E --> F
990
+ F --> G[Development]
991
+ F --> H[Staging]
992
+ F --> I[Production]
993
+ G --> J[Allowed APK output]
994
+ H --> K[Release APK or AAB]
995
+ I --> K
996
+ J --> L[FAST / CLEAN / FULL_RESET]
997
+ K --> L
998
+ L --> M[Validate and show build plan]
999
+ M --> N{Confirm?}
1000
+ N -- No --> O[Cancel, no build]
1001
+ N -- Yes --> P[Upload source to selected Jenkins server]
1002
+ P --> Q[Build APK/AAB and archive artifact]
1003
+ ```
1004
+
1005
+ An example interactive session:
411
1006
 
412
1007
  ```text
413
- Expo
1008
+ ? Mobile build environment / Jenkins server: Immortility — Jenkins PROD
1009
+ ? App type: Expo
1010
+ ? Build type: Production
1011
+ ? Build output: Release AAB
1012
+ ? Build profile: CLEAN
1013
+
1014
+ Build plan: Immortility | Expo | Production | Release AAB | CLEAN
1015
+ ? Create a source snapshot and start this Jenkins mobile build? Yes
414
1016
  ```
415
1017
 
416
- or:
1018
+ **Preview only:**
417
1019
 
418
- ```text
419
- React Native CLI
1020
+ ```powershell
1021
+ indraq mobile build --dry-run
420
1022
  ```
421
1023
 
422
- For an existing mobile project:
1024
+ **Specify values without repeated prompts:**
423
1025
 
424
1026
  ```powershell
425
- indraq project create
1027
+ indraq mobile build --env immortility --type expo --mode prod --output aab --profile clean
1028
+ indraq mobile build --env immortility --type expo --mode dev --profile fast
1029
+ indraq mobile build --env immortility --type native --mode staging --output apk --profile full-reset
426
1030
  ```
427
1031
 
428
- and select **Mobile App**.
1032
+ **Framework note:** `--type native` means **React Native CLI** with an Android Gradle project. This release does not add pure Kotlin/Java Android Studio or iOS native compilation support.
429
1033
 
430
- ---
1034
+ Valid CLI flags: `--env`, `--type expo|native`, `--mode dev|staging|prod`, `--output dev-client|debug-apk|apk|aab`, `--profile fast|clean|full-reset`, `--dry-run`, `--verbose`, `--yes`.
431
1035
 
432
- # Mobile prebuild
1036
+ **Legacy shortcuts still work:** `indraq build mobile:dev`, `indraq build mobile:staging`, `indraq build mobile:prod`, and their previous options. They are compatibility commands; use `indraq mobile build` for the complete interactive experience.
433
1037
 
434
- Inside the mobile project:
1038
+ **Initial setup:** If the selected server has not been linked to the app, the wizard offers to run mobile Jenkins + OTA prebuild automatically. To do so manually:
435
1039
 
436
1040
  ```powershell
437
- indraq prebuild
1041
+ indraq mobile prebuild --env immortility --mode prod
438
1042
  ```
439
1043
 
440
- or:
1044
+ **OTA isolation limitation:** The current Cloud API stores one active native OTA compatibility baseline per mobile environment/app pair. v2.7.9 uses different runtime identifiers (`<version>-indraq-dev`, `-staging`, `-prod`) so updates are never delivered across those build types. Switching build types on the **same** mobile environment replaces its active OTA baseline, which can temporarily prevent OTA updates to previously built modes. For *simultaneous, independent OTA releases* to Development, Staging and Production, create separate mobile environment records—these may all point to the **same Jenkins server**. You do **not** need another physical server.
441
1045
 
442
- ```powershell
443
- indraq mobile prebuild
444
- ```
445
-
446
- Mobile prebuild configures only:
1046
+ Source snapshots exclude `.git`, `.indraq`, `node_modules`, caches and build outputs; root `.env` uploads separately. Release outputs require a root `.env` under the current Jenkinsfile policy.
447
1047
 
448
- - Jenkins
449
- - IndraQ OTA
1048
+ ### 9.5 Understand version fields correctly
450
1049
 
451
- It does not configure:
1050
+ | Field | Example | Where it lives | Who controls it |
1051
+ |---|---|---|---|
1052
+ | App version (`expo.version`) | `1.0.0` | Expo app config | `indraq configure` version setting |
1053
+ | Android `versionCode` | `20` | `expo.android.versionCode` | `indraq configure` versionCode setting |
1054
+ | Apple iOS `buildNumber` | `"15"` | `expo.ios.buildNumber` | **Currently edit manually in Expo app config** |
1055
+ | Jenkins job build number | `#42` | Jenkins job history | Jenkins; shared across builds |
452
1056
 
453
- - Docker
454
- - GitHub Packages
455
- - AWS
456
- - Route53
457
- - Nginx Proxy Manager
1057
+ **Current scope:** v2.7.9 Android build commands manage app version and Android versionCode, not Apple's iOS `buildNumber`. An iOS build-number field in `app.json` does **not** turn these Android build commands into an iOS native build pipeline.
458
1058
 
459
- ---
1059
+ Example Expo config **snippet** (merge it into your existing `expo` object; do not replace the whole file):
460
1060
 
461
- # Mobile builds
1061
+ ```json
1062
+ {
1063
+ "expo": {
1064
+ "version": "1.0.0",
1065
+ "ios": { "buildNumber": "15" },
1066
+ "android": { "versionCode": 20 }
1067
+ }
1068
+ }
1069
+ ```
462
1070
 
463
- Development:
1071
+ To edit the two automated settings:
464
1072
 
465
- ```powershell
466
- indraq build mobile:dev
1073
+ ```text
1074
+ indraq configure
1075
+ -> Mobile App settings
1076
+ -> Version & versionCode
1077
+ -> Change Version or versionCode
1078
+ -> Set auto-increment ON/OFF independently
467
1079
  ```
468
1080
 
469
- Staging:
1081
+ Successful builds can advance enabled counters; failed/cancelled builds do not consume a version. The tool writes the next values locally, so commit the intended `app.json` and `.indraq/mobile.json` changes (not secret files).
470
1082
 
471
- ```powershell
472
- indraq build mobile:staging
473
- ```
1083
+ ### 9.6 OTA lifecycle
474
1084
 
475
- Production:
1085
+ ```mermaid
1086
+ stateDiagram-v2
1087
+ [*] --> NativeBaseline: Successful compatible native build
1088
+ NativeBaseline --> TestRelease: send update to test users
1089
+ TestRelease --> Released: release update
1090
+ TestRelease --> Paused: pause
1091
+ Released --> Paused: pause
1092
+ Released --> Rollback: rollback
1093
+ Rollback --> Released: previous known-good assets
1094
+ ```
476
1095
 
477
1096
  ```powershell
478
- indraq build mobile:prod
1097
+ indraq mobile send update --app "My App" --env immortility
1098
+ indraq mobile metrics --app "My App"
1099
+ indraq mobile release update --app "My App"
1100
+ indraq mobile pause --app "My App"
1101
+ indraq mobile rollback --app "My App"
479
1102
  ```
480
1103
 
481
- A successful native Jenkins build saves the app's native fingerprint in IndraQ Cloud. OTA is allowed only when the current app is compatible with that native build.
1104
+ - **Send update:** build an immutable signed JS/assets release. Select enrolled QA groups, named tester installations, other registered installations, a percentage rollout, or everyone. No per-app email/phone integration is required.
1105
+ - **Release update:** promote the **exact tested release**; no bundle rebuild.
1106
+ - **Pause:** pause an active release.
1107
+ - **Rollback:** republish previous known-good content.
1108
+ - **Metrics:** see installations, manifests, downloads, launches, failures, and rollback activity.
1109
+
1110
+ Eligible installed apps check at **cold startup**; a downloaded compatible update may cause an app reload before normal use.
482
1111
 
483
1112
  ---
484
1113
 
485
- # OTA updates
1114
+ ## 10. Environments, scopes, and permissions
486
1115
 
487
- OTA sends JavaScript and asset changes without publishing a new store build when native code did not change.
1116
+ ### 10.1 What is a provider scope?
488
1117
 
489
- Backend:
1118
+ A **scope** is one named provider connection, such as:
490
1119
 
491
1120
  ```text
492
- https://cli.indraq.com
1121
+ GitHub Packages ── GHCR IndraQ
1122
+ Jenkins DEV ── Jenkins IndraQ
1123
+ Jenkins PROD ── Jenkins Immortility
1124
+ AWS ── AWS Production
1125
+ NPM ── Proxy Server A
493
1126
  ```
494
1127
 
495
- OTA files are stored in MinIO.
1128
+ A project may use different scopes on different deployment environments. A personal default helps when multiple scopes are available but does not give extra privileges.
496
1129
 
497
- ## Send a test update
498
-
499
- ```powershell
500
- indraq mobile send update --app "My App" --env production
1130
+ ```mermaid
1131
+ flowchart TB
1132
+ Org[Organization] --> U[Cloud user]
1133
+ Org --> P[Project]
1134
+ U --> S[Assigned provider scope]
1135
+ U --> R[Project role / resource grant]
1136
+ S --> Target[Provider identity + USE or MANAGE]
1137
+ P --> Env[Project environment]
1138
+ Env --> Target
1139
+ R --> Action[Permitted operation]
1140
+ Target --> Action
501
1141
  ```
502
1142
 
503
- You can target:
1143
+ ### 10.2 Roles and abilities
504
1144
 
505
- - installation ID
506
- - user ID
507
- - username
508
- - email
509
- - phone
510
- - percentage of users
511
- - everyone
1145
+ The platform checks **more than one permission**. Your organization role, project permission, provider-scope permission, and provider-native identity must all permit the attempted action.
512
1146
 
513
- The app checks for an OTA update when the app starts. If an update is found, it downloads it and reloads before the user starts normal work.
1147
+ | Action | USER | MANAGER | ADMIN |
1148
+ |---|---|---|---|
1149
+ | Log in, view assigned scopes | If assigned | If assigned | Yes, subject to scope setup |
1150
+ | Deploy an assigned project | With WRITE + appropriate scope access | With access | With access |
1151
+ | Create organization provider scopes | No | No | Yes |
1152
+ | Create/update shared web/mobile environments | No | No | Yes |
1153
+ | Add a normal user to a MANAGE scope | No | On scopes they manage | Yes |
1154
+ | Change organization roles | No | Limited user management | Admin-only role changes |
1155
+ | Delete Cloud project with external cleanup | No | With required project/scope permissions | With required project/scope permissions |
514
1156
 
515
- ## Release the same tested update to everyone
1157
+ **USE** means permitted use of an assigned provider resource, not unrestricted administration. **MANAGE** allows scoped management actions. Native AWS/Jenkins/NPM/GitHub permissions can further restrict individual operations.
516
1158
 
517
- ```powershell
518
- indraq mobile release update --app "My App"
1159
+ ### 10.3 Why permissions exist
1160
+
1161
+ ```text
1162
+ User identity ──> Project WRITE? ──> Provider MANAGE/USE?
1163
+ |
1164
+ v
1165
+ Provider-native permission?
1166
+ |
1167
+ v
1168
+ Operation
519
1169
  ```
520
1170
 
521
- IndraQ does not rebuild the bundle. It releases the same bundle you already tested.
1171
+ Project membership and provider access are intentionally independent. For example, a developer may see a project but lack the Jenkins scope needed to deploy it.
522
1172
 
523
- ## Metrics
1173
+ ### 10.4 Admin setup order
524
1174
 
525
- ```powershell
526
- indraq mobile metrics --app "My App"
1175
+ ```mermaid
1176
+ flowchart LR
1177
+ A[Create shared environment] --> B[Create provider scopes]
1178
+ B --> C[Assign users / memberships]
1179
+ C --> D[Choose project scope bindings]
1180
+ D --> E[Run prebuild]
1181
+ E --> F[Build and deploy]
527
1182
  ```
528
1183
 
529
- ## Pause an update
1184
+ Admin examples:
530
1185
 
531
1186
  ```powershell
532
- indraq mobile pause --app "My App"
1187
+ indraq environment create
1188
+ indraq scope create github-packages
1189
+ indraq scope create jenkins-dev
1190
+ indraq scope create npm
1191
+ indraq scope create aws
1192
+ indraq mobile environment create
533
1193
  ```
534
1194
 
535
- ## Roll back
1195
+ User/manager scope selection examples:
536
1196
 
537
1197
  ```powershell
538
- indraq mobile rollback --app "My App"
1198
+ indraq scope list
1199
+ indraq scope describe
1200
+ indraq scope default github-packages
1201
+ indraq project scopes --env production
539
1202
  ```
540
1203
 
541
- ---
1204
+ ### 10.5 Audit reasons
1205
+
1206
+ Normal creation/setup uses safe automatic audit reasons in supported flows. Sensitive modifications/deletions may ask for a reason. Audit information helps explain **who changed what, where, and why**.
542
1207
 
543
- # Admin commands
1208
+ ---
544
1209
 
545
- Developers normally do not need this section.
1210
+ ## 11. Safe project deletion
546
1211
 
547
- ## Web environments
1212
+ Deleting a Cloud project is **not the same as deleting every external resource**. The CLI asks you to select which recognized, associated resources should also be deleted.
548
1213
 
549
- Create:
1214
+ ![Safe deletion flow](docs/assets/cleanup.svg)
550
1215
 
551
1216
  ```powershell
552
- indraq environment create
1217
+ indraq project delete
553
1218
  ```
554
1219
 
555
- List:
1220
+ Example selection:
556
1221
 
557
- ```powershell
558
- indraq environment list
1222
+ ```text
1223
+ Delete project: my-old-app
1224
+ Choose external resources to DELETE (unchecked = KEEP):
1225
+
1226
+ [ ] GitHub Packages — ghcr.io/org/my-old-app
1227
+ [x] Jenkins — my-old-app-api
1228
+ [x] NPM — api.example.com
1229
+ [ ] Route53 — api.example.com
559
1230
  ```
560
1231
 
561
- Update:
1232
+ **Default is KEEP.** The deletion plan appears before confirmation, and the CLI asks you to confirm the project identity and provide an audit reason. A resource shared by another IndraQ project must not be deleted through this flow. Shared mobile system jobs are protected.
562
1233
 
563
- ```powershell
564
- indraq environment update <name>
565
- ```
1234
+ | Selected action | What happens |
1235
+ |---|---|
1236
+ | KEEP | External resource is not deleted |
1237
+ | DELETE GHCR package | Removes the **entire container package**, including **all tags/versions** |
1238
+ | DELETE Jenkins job | Deletes the associated supported per-project job; not shared system jobs |
1239
+ | DELETE Route53 record | Deletes matching associated Route53 A record set(s) |
1240
+ | DELETE NPM proxy | Deletes the matching associated NPM proxy host |
1241
+ | Provider deletion fails | Cloud project is retained so you can repair and retry |
1242
+
1243
+ **What is not automatically removed:** live Docker containers, Route53 health checks, shared NPM certificates, and other unlisted provider resources.
1244
+
1245
+ When several NPM scopes exist, select the scope that really owns the proxy and verify its ID/domain. For legacy GHCR scopes missing owner type, the CLI checks the GitHub owner identity before choosing the correct delete endpoint. A token must still have the correct provider deletion permission.
566
1246
 
567
- Delete:
1247
+ ### Archive instead of delete
568
1248
 
569
1249
  ```powershell
570
- indraq environment delete <name>
1250
+ indraq project archive
1251
+ indraq project restore
571
1252
  ```
572
1253
 
573
- ## Mobile environments
1254
+ Archiving is useful when a project should stop deployment mutations but its metadata should remain available. Use permanent deletion only when you no longer need the project and have reviewed its external dependencies.
574
1255
 
575
- Create:
1256
+ ---
576
1257
 
577
- ```powershell
578
- indraq mobile environment create
579
- ```
1258
+ ## 12. Configuration files and secrets
580
1259
 
581
- List:
1260
+ ### 12.1 Typical local files
582
1261
 
583
- ```powershell
584
- indraq mobile environment list
1262
+ ```text
1263
+ my-project/
1264
+ ├── frontend/ # optional
1265
+ ├── backend/ # optional
1266
+ ├── mobile/ # optional
1267
+ │ ├── app.json # Expo config (when using Expo)
1268
+ │ └── .indraq/
1269
+ │ └── mobile.json # mobile settings; commit if intended
1270
+ └── .indraq/
1271
+ └── project.json # local Cloud project reference
585
1272
  ```
586
1273
 
587
- ## Provider connections
1274
+ The CLI saves the **Cloud project ID** locally; infrastructure associations and reusable provider credentials are held by the Cloud control plane. The exact layout depends on whether this is a single-component or combined project.
588
1275
 
589
- Create a provider connection:
1276
+ ### 12.2 Keep and exclude the right files
590
1277
 
591
- ```powershell
592
- indraq scope create
593
- ```
1278
+ | Item | Commit to Git? | Explanation |
1279
+ |---|---|---|
1280
+ | Source code and app config | Yes, after review | Needed by teammates/builds |
1281
+ | `.indraq/mobile.json` | **Yes**, in this workflow | Preserves per-project mobile defaults and version settings |
1282
+ | `.indraq/project.json` | Follow team policy | Stores project identity, not provider secrets |
1283
+ | `.env` and secret values | **No** | Keep out of Git and public archives |
1284
+ | OTA private signing keys / tokens | **No** | Protect credential material |
1285
+ | `node_modules`, caches, build outputs | Usually no | Rebuild/reinstall as needed |
594
1286
 
595
- Provider names shown in the CLI:
1287
+ If the CLI reports **`.indraq/mobile.json is ignored by Git`**, change the `.gitignore` rule so the *specific* mobile config is tracked, without exposing secrets:
596
1288
 
597
- ```text
598
- AWS
599
- Nginx Proxy Manager
600
- Jenkins Development
601
- Jenkins Production
602
- GitHub Packages
603
- ```
1289
+ ```gitignore
1290
+ # Keep private IndraQ files ignored by default
1291
+ .indraq/*
1292
+ !.indraq/mobile.json
604
1293
 
605
- List them:
1294
+ # Mobile subfolder in combined projects
1295
+ mobile/.indraq/*
1296
+ !mobile/.indraq/mobile.json
606
1297
 
607
- ```powershell
608
- indraq scope list
1298
+ # Secrets
1299
+ .env
1300
+ .env.*
1301
+ *.pem
1302
+ *.key
609
1303
  ```
610
1304
 
611
- ## Users
1305
+ If your repository already has an `.indraq/` directory ignore rule, it may also require unignoring the parent directory before Git can add `mobile.json`. Verify the actual result with `git check-ignore -v mobile/.indraq/mobile.json` (or the correct path). Avoid committing certificates or private keys alongside the config.
612
1306
 
613
- Create a user:
1307
+ ### 12.3 `.env` versus `--env`
614
1308
 
615
- ```powershell
616
- indraq user create
1309
+ **They are unrelated.**
1310
+
1311
+ ```text
1312
+ .env Application secrets/config file
1313
+ --env <environment-name> IndraQ deployment or mobile environment selector
617
1314
  ```
618
1315
 
619
- List users:
1316
+ The mobile source ZIP excludes `.env`; when present, the CLI uploads it separately to Jenkins. This does not make `.env` safe to commit or share.
620
1317
 
621
- ```powershell
622
- indraq user list
623
- ```
1318
+ ### 12.4 Expo `app.json` comments
624
1319
 
625
- When IndraQ creates a Nginx Proxy Manager user, it now tests that user's email/password login before reporting success.
1320
+ The CLI v2.7.9 config helper accepts commented Expo `app.json` content and can normalize it before OTA setup. When normalization is needed it preserves a backup in `.indraq/backups/`. Review the diff before committing automatically rewritten config.
626
1321
 
627
1322
  ---
628
1323
 
629
- # Common commands
1324
+ ## 13. Troubleshooting
630
1325
 
631
- | Task | Command |
632
- |---|---|
633
- | Login | `indraq login` |
634
- | Check login | `indraq whoami` |
635
- | Guided setup | `indraq setup` |
636
- | Create project | `indraq project create` |
637
- | Project status | `indraq project status` |
638
- | Choose project servers | `indraq project environments` |
639
- | Configure project services | `indraq prebuild` |
640
- | Deploy web app | `indraq deploy` |
641
- | Create Dockerfile | `indraq dockerfile create` |
642
- | List environments | `indraq environment list` |
643
- | List provider connections | `indraq scope list` |
644
- | Create user | `indraq user create` |
645
- | Run Jenkins pipeline | `indraq jenkins run` |
646
- | Mobile prebuild | `indraq mobile prebuild` |
647
- | Mobile production build | `indraq build mobile:prod` |
648
- | Send OTA | `indraq mobile send update --app "My App"` |
649
- | OTA metrics | `indraq mobile metrics --app "My App"` |
650
- | Main help | `indraq --help` |
651
- | Topic help | `indraq help project` |
1326
+ Use `indraq doctor`, `indraq whoami`, `indraq project status`, and `indraq scope list` first. They frequently explain issues before a destructive retry is needed.
652
1327
 
653
- ---
1328
+ | Symptom | Meaning | Recommended action |
1329
+ |---|---|---|
1330
+ | `indraq` not recognized | CLI not on PATH or not installed | Check `npm install -g indraq_cli`, restart terminal, run `indraq doctor` |
1331
+ | Cloud login rejected | Account/session issue | Try `indraq login` or authorized `indraq password reset` |
1332
+ | `No provider scope` | User/project lacks an assigned provider connection | Check `scope list`; ask manager/admin to grant access or bind a scope |
1333
+ | GHCR package unavailable | Wrong scope, owner, name or permissions | Verify actual package in correct scope and association |
1334
+ | Dockerfile missing | Project component needs Docker setup | Run `indraq dockerfile create` or allow deploy to generate it |
1335
+ | Host port unavailable | Port may already be held by a container/process | Check the owner, choose a free port; don't blindly reuse an occupied port |
1336
+ | Jenkins says `job is not parameterized` (HTTP 400) | Mobile job does not yet expose required parameters | Have a Jenkins administrator fix the existing job and the File Parameter plugin manually; IndraQ never edits the job |
1337
+ | `No active mobile environment exists for Production` | Older CLI still filtered servers by build type | Upgrade to v2.7.9; use `indraq mobile build` and select any authorized mobile server |
1338
+ | `Mobile OTA/Jenkins prebuild is incomplete` | Native build attempted before mobile prebuild/registration | Run `indraq mobile prebuild --env <slug>` |
1339
+ | `Unexpected token '/'` in `app.json` | Strict JSON parser encountered comments (older CLI) | Upgrade to v2.7.9, review the source config and normalization backup |
1340
+ | Windows `Invalid project root` during signing | Older Windows argument-handling bug | Upgrade CLI; rerun mobile prebuild from correct mobile project path |
1341
+ | OTA native fingerprint mismatch | Native config/dependencies changed after last compatible native build | Create a fresh native build, then retry OTA |
1342
+ | NPM cleanup asks to choose scope | Multiple NPM scopes may exist | Verify and explicitly select the correct one; never guess |
1343
+ | GHCR cleanup says owner type missing | Legacy scope configuration/identity needs resolution | Use updated CLI; verify GitHub owner and token rights |
1344
+ | Jenkins/proxy 502 during deploy | Network response may be lost after job began | Check Jenkins before retrying; CLI attempts safe reconnect |
1345
+ | `mobile build:prod` unknown | This shortcut is not a command | Use `indraq mobile build --mode prod` or legacy `indraq build mobile:prod` |
1346
+ | `.indraq/mobile.json ignored by Git` | Settings will be missing after Git clone | Adjust `.gitignore` carefully and commit `mobile.json` |
654
1347
 
655
- # Troubleshooting
1348
+ ### 13.1 Jenkins plugin requirements for mobile
656
1349
 
657
- ## Dockerfile is missing
1350
+ The shared, manually maintained Jenkins mobile job receives a **source bundle** and (when applicable) an **environment file** as file parameters. If Jenkins returns `HTTP 400 ... is not parameterized`, ensure the required Jenkinsfile has been loaded and the **File Parameter** plugin is installed. If Jenkins has not loaded its parameters yet, have a Jenkins administrator initialize or repair it; IndraQ does not attempt any Jenkins configuration changes.
658
1351
 
659
- Run:
1352
+ ### 13.2 If deployment looks stuck
660
1353
 
661
- ```powershell
662
- indraq deploy
1354
+ ```text
1355
+ CLI started Jenkins request
1356
+ |
1357
+ v
1358
+ Response lost?
1359
+ |
1360
+ v
1361
+ Check existing Jenkins queue/build before retry
1362
+ |
1363
+ v
1364
+ Resume / inspect logs instead of starting a duplicate
663
1365
  ```
664
1366
 
665
- and choose **Yes** when IndraQ offers to create the missing Dockerfile(s).
1367
+ IndraQ tries to avoid repeating a Jenkins POST when the reverse proxy returns an uncertain timeout or 502/503/504. If the CLI cannot safely identify the accepted job, inspect Jenkins manually before retrying.
666
1368
 
667
- Or run:
1369
+ ### 13.3 What to send when reporting a bug
668
1370
 
669
- ```powershell
670
- indraq dockerfile create
1371
+ ```text
1372
+ CLI version: indraq --version
1373
+ Operating system: Windows / macOS / Linux
1374
+ Current directory: pwd (PowerShell: Get-Location)
1375
+ Exact command: indraq ...
1376
+ Relevant project type: frontend / backend / mobile / backend-mobile ...
1377
+ Error message: paste the last relevant 20–50 lines
1378
+ Secrets: remove passwords, tokens, .env values, and private keys
671
1379
  ```
672
1380
 
673
- ## Jenkins looks stuck
1381
+ ---
674
1382
 
675
- Do not immediately run deploy again.
1383
+ ## 14. FAQs, glossary, and developer notes
676
1384
 
677
- IndraQ v2.5.0 tries to reconnect to the same Jenkins build.
1385
+ ### Frequently asked questions
678
1386
 
679
- If IndraQ says the result is uncertain, open Jenkins and check whether the build started before retrying.
1387
+ <details>
1388
+ <summary><strong>Do I need to know Jenkins or AWS to deploy a project?</strong></summary>
680
1389
 
681
- ## Nginx Proxy Manager gives 401 for a user
1390
+ Not for the ordinary guided flow. An admin must have configured the shared environments, scopes, credentials, and permissions. Developers then use `indraq setup`, `indraq prebuild`, and `indraq deploy`.
682
1391
 
683
- New users created with v2.5.0 are tested during creation.
1392
+ </details>
684
1393
 
685
- For an old user, rotate/recreate the NPM user credential. IndraQ uses the user's **email address** as the NPM login identity.
1394
+ <details>
1395
+ <summary><strong>Can I link existing Jenkins, Route53, NPM, or GitHub Packages resources?</strong></summary>
686
1396
 
687
- ## Need Route53 or NPM after project creation
1397
+ Yes, the web prebuild workflow can choose an existing association instead of creating or reconciling it. Check provider scope and identity carefully, especially for legacy projects.
688
1398
 
689
- Run:
1399
+ </details>
690
1400
 
691
- ```powershell
692
- indraq prebuild
693
- ```
1401
+ <details>
1402
+ <summary><strong>Can I deploy the same application to two servers?</strong></summary>
694
1403
 
695
- Select only the missing item.
1404
+ Yes. Use `indraq project environments` to configure allowed targets, then `indraq deploy --all`. The same immutable image digest is sent to each server's Jenkins controller.
696
1405
 
697
- ## Need a full setup/repair
1406
+ </details>
698
1407
 
699
- Run:
1408
+ <details>
1409
+ <summary><strong>Can I build an iOS IPA on Windows using `indraq build mobile:prod`?</strong></summary>
700
1410
 
701
- ```powershell
702
- indraq setup
703
- ```
1411
+ No. The v2.7.9 `mobile:dev`, `mobile:staging`, and `mobile:prod` commands are **Android APK/AAB** workflows. Apple signing and native iOS builds need a separate supported macOS/iOS build arrangement. Expo `ios.buildNumber` can be edited manually in the app configuration.
704
1412
 
705
- ---
1413
+ </details>
706
1414
 
707
- # Cloud API development
1415
+ <details>
1416
+ <summary><strong>Does an OTA update require a new native binary?</strong></summary>
708
1417
 
709
- The Cloud API has its own npm dependencies.
1418
+ Not for JavaScript/assets-only changes that match a recorded successful compatible native baseline. Native dependencies or native configuration changes do require a new compatible binary first.
710
1419
 
711
- From the repository root:
1420
+ </details>
712
1421
 
713
- ```powershell
714
- cd cloud-api
715
- npm install
716
- npm run build
717
- npm run dev
718
- ```
1422
+ <details>
1423
+ <summary><strong>Does deleting a project delete its live application container?</strong></summary>
719
1424
 
720
- Running `npm install` in the root folder does not install `cloud-api` dependencies.
1425
+ No, deployed containers are not automatically removed by the selective external cleanup. Review your actual running infrastructure separately.
721
1426
 
722
- Cloud API environment settings are in:
1427
+ </details>
723
1428
 
724
- ```text
725
- cloud-api/.env.example
726
- ```
1429
+ <details>
1430
+ <summary><strong>Why does my Jenkins build number differ from the Android versionCode?</strong></summary>
727
1431
 
728
- ---
1432
+ Jenkins `#42` is a globally increasing job execution ID. Android `versionCode` is native application metadata. They are independent. Apple `ios.buildNumber` is a third, separate native field.
1433
+
1434
+ </details>
729
1435
 
730
- # Before publishing the CLI
1436
+ ### Essential glossary
731
1437
 
732
- From the repository root:
1438
+ | Term | Meaning |
1439
+ |---|---|
1440
+ | **CLI** | Command-line interface: commands typed in a terminal |
1441
+ | **Cloud project** | Central record of an application, components, members, and resource links |
1442
+ | **Component** | Independently built part of a project (frontend, backend, mobile) |
1443
+ | **Environment** | Named deployment server or mobile build/OTA configuration |
1444
+ | **Scope** | Authorized provider account/server connection |
1445
+ | **GHCR** | GitHub Container Registry (`ghcr.io`), part of GitHub Packages |
1446
+ | **Jenkins job** | Automated build or deployment pipeline |
1447
+ | **Docker image** | Packaged application and runtime |
1448
+ | **Digest** | Immutable identifier of the exact Docker image contents |
1449
+ | **Route53** | AWS managed DNS service |
1450
+ | **NPM proxy** | Nginx Proxy Manager host, not the Node package manager |
1451
+ | **APK** | Android installable package |
1452
+ | **AAB** | Android App Bundle for store distribution |
1453
+ | **OTA** | Over-the-air update of compatible app JavaScript/assets |
1454
+ | **Native fingerprint** | Compatibility identifier derived from native app dependencies/configuration |
1455
+ | **Audit reason** | Explanation recorded for an authorized change |
1456
+
1457
+ ### For contributors maintaining IndraQ CLI
1458
+
1459
+ This README describes the **published command behavior**, not private server setup steps. If you change the command surface, update this file and the in-terminal help together.
733
1460
 
734
1461
  ```powershell
1462
+ # In the IndraQ CLI source repository
735
1463
  npm install
736
1464
  npm run build
737
1465
  npm test
738
1466
  npm publish --dry-run
739
1467
  ```
740
1468
 
741
- Then:
1469
+ Cloud API has its own dependency/build step:
742
1470
 
743
1471
  ```powershell
744
- npm publish
1472
+ cd cloud-api
1473
+ npm install
1474
+ npm run build
745
1475
  ```
746
1476
 
1477
+ Only publish after a clean dependency-backed TypeScript build, tests, and an npm package-content audit. The CLI and Cloud API need compatible versions for server-side authorization changes.
1478
+
747
1479
  ---
748
1480
 
749
- **IndraQ Innovations — IndraQ CLI v2.7.1**
1481
+ <div align="center">
750
1482
 
1483
+ **IndraQ CLI — build once, deploy deliberately, and manage infrastructure with clear permissions.**
751
1484
 
752
- ---
1485
+ Maintained by **IndraQ Innovations Private Limited** · Documented for CLI **v2.7.9**
1486
+
1487
+ </div>
753
1488
 
754
- # What is new in v2.6.0
755
1489
 
756
- ## Backend + Mobile App
1490
+ ## Fixing Jenkins HTTP 400: job is not parameterized
757
1491
 
758
- Choose **Backend + Mobile App** under `indraq init` or `indraq project create`.
759
- The backend lives in `backend/` and uses normal Docker, GitHub Packages, Jenkins,
760
- Route53, and NPM provisioning. The mobile app lives in `mobile/` and uses
761
- Jenkins native builds and IndraQ OTA. `indraq setup` configures both once.
1492
+ Mobile build uses `indraq mobile build`. In v2.7.9, the CLI checks that the chosen Jenkins job has required parameters **before** uploading the source snapshot. If parameters are missing, it stops immediately and asks you to repair the job manually in Jenkins; it never edits any Pipeline setting.
762
1493
 
763
- ## Project deletion cleanup
1494
+ `indraq mobile prebuild --env immortility` validates the pre-existing mobile Jenkins job and required parameters without changing Jenkins. The Jenkins File Parameter plugin (`file-parameters`) is required for `SOURCE_BUNDLE` and `ENV_FILE`. Users need Jenkins Job/Read and Job/Build permissions. All Jenkins job changes must be made manually by a Jenkins administrator.
764
1495
 
765
- `indraq project delete` lists the actual resources linked to the project and
766
- asks which to delete: Route53 A records, GitHub Packages container packages,
767
- project-specific Jenkins jobs, and NPM proxy hosts. **Everything starts as KEEP.**
768
- Shared resources and the shared mobile Jenkins pipeline are protected.
769
- An external resource marked as linked requires extra approval to delete.
770
- If any chosen provider deletion fails, the Cloud project stays available for retry.
771
- Deleting GitHub Packages removes all tags and versions of the selected package.
772
- AWS health checks, NPM certificates, running containers, and local source files
773
- are not automatically deleted. `--yes` does not select any resources automatically.
1496
+ If you still see HTTP 400, have a Jenkins administrator check that the job is parameterized and the File Parameter plugin is active. IndraQ will not attempt automatic repair.
1497
+
1498
+
1499
+ ## Jenkins mobile Pipeline protection (v2.7.9)
1500
+
1501
+ For the existing shared job `Mobile app Cli build`, **IndraQ never replaces your Jenkins Pipeline script** during `indraq mobile prebuild` or `indraq mobile build`.
1502
+
1503
+ - `indraq mobile build` **never modifies Jenkins job configuration**. It validates parameters, uploads the source, and starts the existing job. If required parameters are missing, it stops and asks a Jenkins administrator to repair the job manually.
1504
+ - `indraq mobile prebuild` **never creates or changes a Jenkins job**. It only verifies the existing Pipeline job, parameters and access, then performs IndraQ OTA configuration. Missing or incorrect job parameters cause a clear error; fix them directly in Jenkins.
1505
+ - If a required parameter already exists with an incompatible type or choice list, prebuild **stops instead of overwriting it**. An administrator should resolve the conflict explicitly in Jenkins.
1506
+ - Updating the Pipeline script remains a manual Jenkins operation. The CLI does **not** automatically deploy new pipeline script revisions into an existing job.
1507
+
1508
+ > Deployment: deploy Cloud API **v1.3.5** before using CLI **v2.7.9**.
1509
+
1510
+ ### Mobile Jenkins job: manual setup and repair
1511
+
1512
+ Before using IndraQ mobile prebuild/build, an administrator must configure an existing Jenkins **Pipeline** job named exactly `Mobile app Cli build`. Install the **File Parameter** plugin and load your maintained Pipeline script in Jenkins. IndraQ **never** submits a script, calls `createItem`, writes `config.xml`, or adds/changes job parameters.
1513
+
1514
+ | Required Jenkins parameters | Type |
1515
+ |---|---|
1516
+ | `SOURCE_BUNDLE`, `ENV_FILE` | `stashedFile` (File Parameter plugin) |
1517
+ | `PROJECT_ID`, `APP_NAME`, `APP_VERSION`, `APP_VERSION_CODE`, `SOURCE_SHA256`, `SOURCE_REVISION` | String |
1518
+ | `PROJECT_TYPE` | Choice: Expo, React Native CLI |
1519
+ | `BUILD_ENVIRONMENT` | Choice: Development, Staging, Production |
1520
+ | `BUILD_OUTPUT` | Choice: Development Client, Debug APK, Release APK, Release AAB |
1521
+ | `BUILD_PROFILE` | Choice: FAST, CLEAN, FULL_RESET |
1522
+ | `SOURCE_DIRTY`, `VERBOSE_BUILD` | Boolean |
774
1523
 
775
- ## Windows OTA signing fix
1524
+ The CLI reads the job type, enabled/buildable status, parameters, file types and choices. If invalid, it prints what needs manual repair **before uploading any source**. If valid, the build uses only Jenkins' `buildWithParameters` endpoint, streams the output, and leaves job configuration untouched. A real build naturally creates build history/artifacts, not Jenkins job configuration changes.
776
1525
 
777
- `expo-updates codesigning:generate` now uses a Windows-safe argument-preserving
778
- `npx` launcher. Temporary private key material is cleaned up after errors too.
1526
+ **Older CLI versions:** Deploy Cloud API v1.3.5 first. It rejects the legacy create/repair mobile operations with HTTP 409, so older CLI clients cannot modify the shared mobile job through IndraQ Cloud either.