indraq_cli 2.7.3 → 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 (56) hide show
  1. package/README.md +1526 -0
  2. package/cloud-api/README.md +6 -0
  3. package/cloud-api/dist/index.js +246 -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 +187 -44
  7. package/dist/cli/help-content.d.ts.map +1 -1
  8. package/dist/cli/help-content.js +13 -3
  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.js +3 -3
  15. package/dist/modules/mobile/commands/build-mobile.command.js.map +1 -1
  16. package/dist/modules/mobile/commands/configure-mobile.command.js +1 -1
  17. package/dist/modules/mobile/commands/configure-mobile.command.js.map +1 -1
  18. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts.map +1 -1
  19. package/dist/modules/mobile/commands/mobile-prebuild.command.js +20 -14
  20. package/dist/modules/mobile/commands/mobile-prebuild.command.js.map +1 -1
  21. package/dist/modules/mobile/commands/ota.command.d.ts.map +1 -1
  22. package/dist/modules/mobile/commands/ota.command.js +33 -15
  23. package/dist/modules/mobile/commands/ota.command.js.map +1 -1
  24. package/dist/modules/mobile/commands/testers.command.d.ts +6 -0
  25. package/dist/modules/mobile/commands/testers.command.d.ts.map +1 -0
  26. package/dist/modules/mobile/commands/testers.command.js +143 -0
  27. package/dist/modules/mobile/commands/testers.command.js.map +1 -0
  28. package/dist/modules/mobile/index.d.ts.map +1 -1
  29. package/dist/modules/mobile/index.js +23 -1
  30. package/dist/modules/mobile/index.js.map +1 -1
  31. package/dist/modules/mobile/services/mobile-cloud.service.d.ts +61 -0
  32. package/dist/modules/mobile/services/mobile-cloud.service.d.ts.map +1 -1
  33. package/dist/modules/mobile/services/mobile-cloud.service.js +15 -1
  34. package/dist/modules/mobile/services/mobile-cloud.service.js.map +1 -1
  35. package/dist/modules/mobile/services/ota-identity.service.d.ts +20 -0
  36. package/dist/modules/mobile/services/ota-identity.service.d.ts.map +1 -0
  37. package/dist/modules/mobile/services/ota-identity.service.js +169 -0
  38. package/dist/modules/mobile/services/ota-identity.service.js.map +1 -0
  39. package/dist/modules/mobile/services/ota-setup.service.d.ts +1 -0
  40. package/dist/modules/mobile/services/ota-setup.service.d.ts.map +1 -1
  41. package/dist/modules/mobile/services/ota-setup.service.js +268 -24
  42. package/dist/modules/mobile/services/ota-setup.service.js.map +1 -1
  43. package/package.json +16 -4
  44. package/vendor/QR-CODE-APACHE-2.0-LICENSE.txt +222 -0
  45. package/vendor/QR-CODE-MIT-LICENSE.txt +21 -0
  46. package/vendor/QR-CODE-NOTICE.txt +6 -0
  47. package/vendor/QRCode/QR8bitByte.js +22 -0
  48. package/vendor/QRCode/QRBitBuffer.js +38 -0
  49. package/vendor/QRCode/QRErrorCorrectLevel.js +7 -0
  50. package/vendor/QRCode/QRMaskPattern.js +10 -0
  51. package/vendor/QRCode/QRMath.js +44 -0
  52. package/vendor/QRCode/QRMode.js +6 -0
  53. package/vendor/QRCode/QRPolynomial.js +66 -0
  54. package/vendor/QRCode/QRRSBlock.js +298 -0
  55. package/vendor/QRCode/QRUtil.js +272 -0
  56. package/vendor/QRCode/index.js +462 -0
package/README.md ADDED
@@ -0,0 +1,1526 @@
1
+ # IndraQ CLI — developer guide (v2.7.9)
2
+
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
+
5
+ <div align="center">
6
+ <img src="docs/assets/indraq-logo.png" alt="IndraQ Innovations" width="240" />
7
+
8
+ # IndraQ CLI
9
+
10
+ **One command-line workspace for creating, connecting, building, deploying, and maintaining web and mobile projects.**
11
+
12
+ `v2.7.9` · `Node.js 22+` · `Windows / macOS / Linux` · `IndraQ Cloud` · `Jenkins` · `Docker` · `Expo / React Native`
13
+ </div>
14
+
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.
16
+
17
+ ## OTA activation reliability (v2.7.9)
18
+
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.
20
+
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.
22
+
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.
24
+
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.
26
+
27
+ ## Automatic device enrollment & targeting (v2.7.9)
28
+
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.
30
+
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
+ ```
46
+
47
+ The Project's IndraQ owner runs this **once** from the source checkout; it does not edit Jenkins:
48
+
49
+ ```powershell
50
+ indraq mobile prebuild --env immortility --mode prod
51
+ indraq mobile build --env immortility --type expo --mode prod --output apk --profile fast
52
+ ```
53
+
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.
55
+
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):
57
+
58
+ ```powershell
59
+ indraq mobile testers invite
60
+ ```
61
+
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.
63
+
64
+ ```powershell
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
70
+ ```
71
+
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
+
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.
83
+
84
+ ---
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.
103
+
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.
105
+
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.
109
+
110
+ ```powershell
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
114
+ ```
115
+
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?
119
+
120
+ ```powershell
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
124
+ ```
125
+
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
+ ---
140
+
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
+ ---
159
+
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:
165
+
166
+ ```powershell
167
+ indraq setup
168
+ ```
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
+
243
+ ---
244
+
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):
263
+
264
+ ```powershell
265
+ node -v
266
+ npm -v
267
+ npm install -g indraq_cli
268
+ indraq --version
269
+ indraq --help
270
+ ```
271
+
272
+ The npm package name is `indraq_cli`; the terminal command is **`indraq`**.
273
+
274
+ To update an installation:
275
+
276
+ ```powershell
277
+ npm install -g indraq_cli@latest
278
+ indraq --version
279
+ ```
280
+
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.
282
+
283
+ ### 3.3 Log in once
284
+
285
+ ```powershell
286
+ indraq login
287
+ indraq whoami
288
+ ```
289
+
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.
291
+
292
+ ```powershell
293
+ indraq logout
294
+ ```
295
+
296
+ This revokes your persistent session and clears the local session credentials.
297
+
298
+ ### 3.4 First command to learn
299
+
300
+ ```powershell
301
+ indraq setup
302
+ ```
303
+
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.
305
+
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
322
+
323
+ ```text
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/
333
+ ```
334
+
335
+ Paths above are examples. Single-component projects may use the root folder directly. Existing application files are preserved during `indraq project create`.
336
+
337
+ ### 4.2 One project, two different build paths
338
+
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.
342
+
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
+ ```
353
+
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.
362
+
363
+ ---
364
+
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
370
+
371
+ ```powershell
372
+ cd C:\Projects\my-backend
373
+ indraq login
374
+ indraq project create
375
+ indraq prebuild
376
+ indraq project status
377
+ indraq deploy
378
+ ```
379
+
380
+ During project creation you can choose an environment and one setup checklist:
381
+
382
+ ```text
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
389
+ ```
390
+
391
+ Select only what you need. You can always run `indraq prebuild` later to add optional infrastructure.
392
+
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
399
+ ```
400
+
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.
402
+
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
411
+ ```
412
+
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.
414
+
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.
416
+
417
+ ### Recipe D — Backend + Mobile App
418
+
419
+ ```powershell
420
+ cd C:\Projects\my-combined-project
421
+ indraq project create
422
+ ```
423
+
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.
425
+
426
+ Later, work from either subfolder:
427
+
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
436
+ ```
437
+
438
+ ### Recipe E — Deploy the same web image to multiple servers
439
+
440
+ ```powershell
441
+ indraq project environments
442
+ indraq prebuild --all-targets
443
+ indraq deploy --all
444
+ ```
445
+
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.
447
+
448
+ ### Recipe F — Make an OTA update after a successful native build
449
+
450
+ ```powershell
451
+ indraq mobile send update --app "My App" --env <mobile-environment-slug>
452
+ indraq mobile metrics --app "My App"
453
+ ```
454
+
455
+ Test the update with a limited audience before running:
456
+
457
+ ```powershell
458
+ indraq mobile release update --app "My App"
459
+ ```
460
+
461
+ OTA is for compatible JavaScript and asset changes, **not** changes requiring a new native binary.
462
+
463
+ ---
464
+
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?”**
690
+
691
+ ### 7.1 `login`, `logout`, `whoami`, `password reset`
692
+
693
+ ```powershell
694
+ indraq login
695
+ indraq whoami
696
+ indraq password reset
697
+ indraq logout
698
+ ```
699
+
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.
704
+
705
+ ### 7.2 `init`
706
+
707
+ ```powershell
708
+ indraq init
709
+ indraq init C:\Projects\my-app
710
+ indraq init --skip-install
711
+ ```
712
+
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.
716
+
717
+ ### 7.3 `project create`, `project link`, `project status`
718
+
719
+ ```powershell
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
725
+ ```
726
+
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`
732
+
733
+ ```powershell
734
+ indraq project environments
735
+ indraq project scopes --env production
736
+ indraq scope list
737
+ ```
738
+
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.
755
+
756
+ ```powershell
757
+ indraq prebuild
758
+ indraq prebuild --env my-server
759
+ indraq prebuild --all-targets
760
+ indraq prebuild --required-only
761
+ ```
762
+
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
+ ```
773
+
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`.
775
+
776
+ **`--env` does not choose a `.env` file.** It selects the IndraQ infrastructure environment.
777
+
778
+ ### 7.7 `dockerfile create`
779
+
780
+ ```powershell
781
+ indraq dockerfile create
782
+ ```
783
+
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**.
793
+
794
+ ```text
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
803
+ ```
804
+
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`
808
+
809
+ ```powershell
810
+ indraq jenkins pipelines --stage dev
811
+ indraq jenkins build --stage dev
812
+ indraq jenkins build "My Pipeline" --stage prod
813
+ ```
814
+
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`
818
+
819
+ ```powershell
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
827
+ ```
828
+
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.
833
+
834
+ ### 7.11 `environment`, `dns`, `proxy`, `iam`, `healthcheck`, `npm-user`
835
+
836
+ These are **infrastructure/admin tools**. Use the guided project workflow for routine deployments. Direct commands are available for authorized diagnostics and management.
837
+
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 |
846
+
847
+ All direct commands still enforce the relevant IndraQ/project/provider permissions.
848
+
849
+ ---
850
+
851
+ ## 8. Web deployment: from code to server
852
+
853
+ ### 8.1 Where the application goes
854
+
855
+ ![Web deploy pipeline](docs/assets/web-deployment.svg)
856
+
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
+ ```
874
+
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
878
+
879
+ ```text
880
+ Code -> Docker image -> GitHub Packages -> Jenkins -> Running container
881
+ |
882
+ Public DNS (Route53) ---> Public IP ---> NPM proxy ---> Internal IP:port
883
+ ```
884
+
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
892
+
893
+ ```text
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
907
+ ```
908
+
909
+ **Do not swap them:** Route53 receives the environment's *external/public IPv4*, while NPM uses its *internal/private IPv4* as the upstream.
910
+
911
+ ### 8.4 Link existing versus create/reconcile
912
+
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.
914
+
915
+ Example:
916
+
917
+ ```text
918
+ GitHub Packages for backend:
919
+ ○ Create/reconcile package association
920
+ ● Link existing container package (do not modify)
921
+
922
+ Choose package: barakah-backend
923
+ ✓ Linked ghcr.io/organization/barakah-backend
924
+ ```
925
+
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.
927
+
928
+ ---
929
+
930
+ ## 9. Mobile builds and OTA updates
931
+
932
+ ### 9.1 Two separate workflows
933
+
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
+ ```
945
+
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.
947
+
948
+ ### 9.2 Supported Android build matrix
949
+
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 |
954
+
955
+ **Build profiles:**
956
+
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 |
962
+
963
+ ### 9.3 Create a reusable mobile build environment
964
+
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.
966
+
967
+ ```powershell
968
+ indraq mobile environment list
969
+ # Administrator only (when adding a new build environment):
970
+ indraq mobile environment create
971
+ ```
972
+
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.
974
+
975
+ ### 9.4 Guided Android builds (recommended)
976
+
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:
1006
+
1007
+ ```text
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
1016
+ ```
1017
+
1018
+ **Preview only:**
1019
+
1020
+ ```powershell
1021
+ indraq mobile build --dry-run
1022
+ ```
1023
+
1024
+ **Specify values without repeated prompts:**
1025
+
1026
+ ```powershell
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
1030
+ ```
1031
+
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.
1033
+
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`.
1035
+
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.
1037
+
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:
1039
+
1040
+ ```powershell
1041
+ indraq mobile prebuild --env immortility --mode prod
1042
+ ```
1043
+
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.
1045
+
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.
1047
+
1048
+ ### 9.5 Understand version fields correctly
1049
+
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 |
1056
+
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.
1058
+
1059
+ Example Expo config **snippet** (merge it into your existing `expo` object; do not replace the whole file):
1060
+
1061
+ ```json
1062
+ {
1063
+ "expo": {
1064
+ "version": "1.0.0",
1065
+ "ios": { "buildNumber": "15" },
1066
+ "android": { "versionCode": 20 }
1067
+ }
1068
+ }
1069
+ ```
1070
+
1071
+ To edit the two automated settings:
1072
+
1073
+ ```text
1074
+ indraq configure
1075
+ -> Mobile App settings
1076
+ -> Version & versionCode
1077
+ -> Change Version or versionCode
1078
+ -> Set auto-increment ON/OFF independently
1079
+ ```
1080
+
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).
1082
+
1083
+ ### 9.6 OTA lifecycle
1084
+
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
+ ```
1095
+
1096
+ ```powershell
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"
1102
+ ```
1103
+
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.
1111
+
1112
+ ---
1113
+
1114
+ ## 10. Environments, scopes, and permissions
1115
+
1116
+ ### 10.1 What is a provider scope?
1117
+
1118
+ A **scope** is one named provider connection, such as:
1119
+
1120
+ ```text
1121
+ GitHub Packages ── GHCR IndraQ
1122
+ Jenkins DEV ── Jenkins IndraQ
1123
+ Jenkins PROD ── Jenkins Immortility
1124
+ AWS ── AWS Production
1125
+ NPM ── Proxy Server A
1126
+ ```
1127
+
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.
1129
+
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
1141
+ ```
1142
+
1143
+ ### 10.2 Roles and abilities
1144
+
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.
1146
+
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 |
1156
+
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.
1158
+
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
1169
+ ```
1170
+
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.
1172
+
1173
+ ### 10.4 Admin setup order
1174
+
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]
1182
+ ```
1183
+
1184
+ Admin examples:
1185
+
1186
+ ```powershell
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
1193
+ ```
1194
+
1195
+ User/manager scope selection examples:
1196
+
1197
+ ```powershell
1198
+ indraq scope list
1199
+ indraq scope describe
1200
+ indraq scope default github-packages
1201
+ indraq project scopes --env production
1202
+ ```
1203
+
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**.
1207
+
1208
+ ---
1209
+
1210
+ ## 11. Safe project deletion
1211
+
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.
1213
+
1214
+ ![Safe deletion flow](docs/assets/cleanup.svg)
1215
+
1216
+ ```powershell
1217
+ indraq project delete
1218
+ ```
1219
+
1220
+ Example selection:
1221
+
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
1230
+ ```
1231
+
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.
1233
+
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.
1246
+
1247
+ ### Archive instead of delete
1248
+
1249
+ ```powershell
1250
+ indraq project archive
1251
+ indraq project restore
1252
+ ```
1253
+
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.
1255
+
1256
+ ---
1257
+
1258
+ ## 12. Configuration files and secrets
1259
+
1260
+ ### 12.1 Typical local files
1261
+
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
1272
+ ```
1273
+
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.
1275
+
1276
+ ### 12.2 Keep and exclude the right files
1277
+
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 |
1286
+
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:
1288
+
1289
+ ```gitignore
1290
+ # Keep private IndraQ files ignored by default
1291
+ .indraq/*
1292
+ !.indraq/mobile.json
1293
+
1294
+ # Mobile subfolder in combined projects
1295
+ mobile/.indraq/*
1296
+ !mobile/.indraq/mobile.json
1297
+
1298
+ # Secrets
1299
+ .env
1300
+ .env.*
1301
+ *.pem
1302
+ *.key
1303
+ ```
1304
+
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.
1306
+
1307
+ ### 12.3 `.env` versus `--env`
1308
+
1309
+ **They are unrelated.**
1310
+
1311
+ ```text
1312
+ .env Application secrets/config file
1313
+ --env <environment-name> IndraQ deployment or mobile environment selector
1314
+ ```
1315
+
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.
1317
+
1318
+ ### 12.4 Expo `app.json` comments
1319
+
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.
1321
+
1322
+ ---
1323
+
1324
+ ## 13. Troubleshooting
1325
+
1326
+ Use `indraq doctor`, `indraq whoami`, `indraq project status`, and `indraq scope list` first. They frequently explain issues before a destructive retry is needed.
1327
+
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` |
1347
+
1348
+ ### 13.1 Jenkins plugin requirements for mobile
1349
+
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.
1351
+
1352
+ ### 13.2 If deployment looks stuck
1353
+
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
1365
+ ```
1366
+
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.
1368
+
1369
+ ### 13.3 What to send when reporting a bug
1370
+
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
1379
+ ```
1380
+
1381
+ ---
1382
+
1383
+ ## 14. FAQs, glossary, and developer notes
1384
+
1385
+ ### Frequently asked questions
1386
+
1387
+ <details>
1388
+ <summary><strong>Do I need to know Jenkins or AWS to deploy a project?</strong></summary>
1389
+
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`.
1391
+
1392
+ </details>
1393
+
1394
+ <details>
1395
+ <summary><strong>Can I link existing Jenkins, Route53, NPM, or GitHub Packages resources?</strong></summary>
1396
+
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.
1398
+
1399
+ </details>
1400
+
1401
+ <details>
1402
+ <summary><strong>Can I deploy the same application to two servers?</strong></summary>
1403
+
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.
1405
+
1406
+ </details>
1407
+
1408
+ <details>
1409
+ <summary><strong>Can I build an iOS IPA on Windows using `indraq build mobile:prod`?</strong></summary>
1410
+
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.
1412
+
1413
+ </details>
1414
+
1415
+ <details>
1416
+ <summary><strong>Does an OTA update require a new native binary?</strong></summary>
1417
+
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.
1419
+
1420
+ </details>
1421
+
1422
+ <details>
1423
+ <summary><strong>Does deleting a project delete its live application container?</strong></summary>
1424
+
1425
+ No, deployed containers are not automatically removed by the selective external cleanup. Review your actual running infrastructure separately.
1426
+
1427
+ </details>
1428
+
1429
+ <details>
1430
+ <summary><strong>Why does my Jenkins build number differ from the Android versionCode?</strong></summary>
1431
+
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>
1435
+
1436
+ ### Essential glossary
1437
+
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.
1460
+
1461
+ ```powershell
1462
+ # In the IndraQ CLI source repository
1463
+ npm install
1464
+ npm run build
1465
+ npm test
1466
+ npm publish --dry-run
1467
+ ```
1468
+
1469
+ Cloud API has its own dependency/build step:
1470
+
1471
+ ```powershell
1472
+ cd cloud-api
1473
+ npm install
1474
+ npm run build
1475
+ ```
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
+
1479
+ ---
1480
+
1481
+ <div align="center">
1482
+
1483
+ **IndraQ CLI — build once, deploy deliberately, and manage infrastructure with clear permissions.**
1484
+
1485
+ Maintained by **IndraQ Innovations Private Limited** · Documented for CLI **v2.7.9**
1486
+
1487
+ </div>
1488
+
1489
+
1490
+ ## Fixing Jenkins HTTP 400: job is not parameterized
1491
+
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.
1493
+
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.
1495
+
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 |
1523
+
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.
1525
+
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.