@apps-in-toss/cli 3.1.0-beta.0 → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# @apps-in-toss/cli
+
+## 3.1.0
+
+## 3.0.5
+
+## 3.0.4
+
+### Patch Changes
+
+- 6e935ed: - webView.pullToRefreshEnabled 기본값을 false로 변경해요.
+  - ait --help를 개선해요 (ko/en, --version, 컬러/라우팅 정리).
+  - 빌드 시 appName·brand·webBundle validation을 추가해요.
+  - 라이선스를 Apache-2.0으로 변경해요.
+- 99d1861: fix: `--help` 표면 전반을 정비해요.
+
+  - help 출력의 바이너리 이름과 모든 예시를 실제 bin인 `ait`로 통일하고, `ait --version`을 지원해요. `deploy`·`init`·`build`·`migrate`·`token` 각 커맨드의 설명과 details를 실제 동작 기준으로 보강해요(API 키 해석 순서, `migrate v3`가 수행하는 변환 내용, 토큰 저장 위치 등).
+  - 컬러 미지원 환경(비-TTY 파이프·`NO_COLOR`·dumb 터미널)에서 CLI 출력에 ANSI 코드를 남기지 않아요 — clipanion이 렌더링하는 `--help`·에러 표면 포함.
+  - `--help`를 한국어와 영어로 제공해요. `AIT_LANG` 환경변수(`ko`/`en`)를 최우선으로 보고, 없으면 `LC_ALL` → `LC_CTYPE` → `LANG` 순으로 감지해요. 출력 끝에 반대편 언어로 전환하는 방법을 안내하는 힌트 한 줄을 추가해요.
+  - help 요청이 어떤 형태로 오든(`ait <command> --help`/`-h`, `ait help <command>`, `ait token` 그룹 help) 같은 스타일과 힌트 줄로 출력하도록 하나의 라우터로 통일하고, `token`에서 clipanion의 "Multiple commands match your selection" 목록이 뜨던 문제를 없앴어요. `ait help <존재하지 않는 명령어>`는 스타일드 에러와 함께 종료 코드 1로 끝나요.
+
+- 732a23a: validation을 추가합니다. (app-name, brand, webBundle)
+
+## 3.0.3
+
+### Patch Changes
+
+- e068bb8: fix: 빌드 아티팩트의 `sdkVersion`이 실제 설치된 web-framework 버전과 어긋나던 문제를 고쳐요.
+
+  - web-framework가 의존하는 `@apps-in-toss/cli` 버전을 캐럿 범위 대신 정확한 버전으로 고정해요.
+  - CLI가 아티팩트 메타데이터에 자신의 버전 대신, 프로젝트에 실제 설치된 `@apps-in-toss/web-framework`의 버전을 기록해요. web-framework 없이 CLI만 쓰는 프로젝트에서는 기존처럼 CLI 버전을 남겨요.
+
+## 3.0.2
+
+### Patch Changes
+
+- 5519b6f: feat: `@apps-in-toss/devtools` 패키지를 추가해요 — 브라우저에서 미니앱을 개발할 수 있는 mock SDK, devtools 패널, 번들러 unplugin(vite/webpack/rspack/rollup/esbuild)을 제공해요. `ait init`과 `ait migrate v3`가 devtools를 devDependencies에 추가하고, 번들러 설정의 plugins 맨 앞에 unplugin을 자동으로 꽂은 뒤 의존성 설치까지 실행해요.
+
+## 3.0.1
+
+### Patch Changes
+
+- 2c9ac93: V3 레퍼런스 추가
+
+## 3.0.0
+
+### Major Changes
+
+- 134f42c: 3.0.0 릴리즈 — granite 아키텍처(브릿지 SSoT 이전, 파일 라우터 공개 API, 문서 파이프라인)
+
+### Patch Changes
+
+- 975049b: migrate v3 커맨드를 고쳐요. TypeScript 설정 파일 파싱 실패를 수정하고, 모든 조건을 검증한 뒤 트랜잭션으로 실행하도록 바꿔요. 마이그레이션이 끝나면 granite.config를 삭제하고 유의사항을 안내해요.
+- 245f18d: 라이센스 추가
+
+## 3.0.0-rc.4
+
+### Patch Changes
+
+- 245f18d: 라이센스 추가
+
+## 3.0.0-rc.3
+
+## 3.0.0-rc.2
+
+### Patch Changes
+
+- 975049b: migrate v3 커맨드를 고쳐요. TypeScript 설정 파일 파싱 실패를 수정하고, 모든 조건을 검증한 뒤 트랜잭션으로 실행하도록 바꿔요. 마이그레이션이 끝나면 granite.config를 삭제하고 유의사항을 안내해요.
+
+## 3.0.0-rc.1
+
+## 3.0.0-rc.0
+
+### Major Changes
+
+- 3.0.0 릴리즈 — granite 아키텍처(브릿지 SSoT 이전, 파일 라우터 공개 API, 문서 파이프라인)

package/LICENSE

@@ -1,28 +1,201 @@
-BSD 3-Clause License
-
-Copyright (c) 2026, Viva Republica, Inc.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Viva Republica, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { Builtins, Cli, Command, Option } from "clipanion";
+import { Builtins, Cli, Command, Option, formatMarkdownish } from "clipanion";
 import * as p from "@clack/prompts";
 import path from "path";
 import { appendFile, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
@@ -10,10 +10,251 @@ import { loadConfig } from "c12";
 import { uuidv7 } from "uuidv7";
 import fs, { existsSync, readFileSync } from "node:fs";
 import assert from "node:assert";
+import pc from "picocolors";
 import os from "node:os";
 import { setTimeout } from "node:timers/promises";
 import jscodeshift from "jscodeshift";
 import { spawn } from "node:child_process";
+//#region src/i18n/en.ts
+const en = {
+	"groupHelp.commandsHeader": "Commands",
+	"groupHelp.detailHint": "You can also print more details about any of these commands by calling them with the -h,--help flag right after the command name.",
+	"help.unknownPath": "Couldn't find the '{path}' command.",
+	"help.unknownPath.guide": "See the available commands below.",
+	"build.description": "Reads the config file (apps-in-toss.config) and builds a deployable .ait artifact.",
+	"build.details": `
+      Reads apps-in-toss.config.(ts|js|mjs) from the project root (the directory containing package.json) and builds a .ait artifact. This fails if that config file doesn't exist — create one first with \`ait init\` for a new project, or \`ait migrate v3\` for an existing granite.config project.
+
+      The directory set as webBundleDir in apps-in-toss.config is packed into the artifact as-is, so before running this command you need to run your web framework's build command (e.g. vite build) so that directory has build output that includes index.html.
+
+      The finished artifact is saved as \`<appName>.ait\` in the project root, and \`ait deploy\` finds and uploads this file.
+    `,
+	"build.example.artifact.label": "Build artifact",
+	"deploy.description": "Uploads (deploys) a built .ait artifact to Apps in Toss.",
+	"deploy.details": `
+      The API key is resolved in this order:
+
+      - If a token is saved for the profile named by \`--profile\` (or \`default\` when not given), that token is used.
+      - If no saved token exists, the value passed directly via \`--api-key\` is used.
+      - If neither is available, you're prompted interactively for the API key.
+
+      To save a token for a profile ahead of time, register it first with \`ait token add\`.
+    `,
+	"deploy.example.default.label": "Deploy the default artifact (.ait)",
+	"deploy.example.location.label": "Deploy a specific .ait file",
+	"deploy.example.profile.label": "Deploy using a token saved in a profile",
+	"deploy.example.memo.label": "Deploy with release notes",
+	"deploy.example.memo.cmd": "ait deploy -m \"Release notes (up to 1000 chars)\"",
+	"deploy.example.schemeOnly.label": "Print only the deployment result scheme",
+	"deploy.option.apiKey": "The API key to use for deployment. Either pass it directly with this option, or use --profile to specify a profile and use the API key registered for it.",
+	"deploy.option.workspace": "(deprecated) The token workspace name. Use --profile instead.",
+	"deploy.option.profile": "A profile registered in ~/.ait/credentials via the ait token add command. Falls back to the default profile if none is given.",
+	"deploy.option.baseUrl": "Directly overrides the base URL of the deploy API. Not needed for a normal deploy — only used when testing against a separate environment.",
+	"deploy.option.location": "Explicitly sets the path to the .ait file to upload. If omitted, uses the first .ait file found in the current package root directory.",
+	"deploy.option.schemeOnly": "Makes the deploy print only the intoss-private scheme for the result. Defaults to false.",
+	"deploy.option.memo": "Sets the release notes. Up to 1000 characters.",
+	"init.description": "Adds the settings needed to deploy to Apps in Toss to an existing web project.",
+	"init.details": `
+      Doesn't create a new project — run this inside an existing web project that has a package.json (e.g. one created with Vite).
+
+      Running it does the following:
+
+      - Asks for an app name (kebab-case) and the web bundle output directory (default: dist).
+      - Creates an apps-in-toss.config.ts file.
+      - If package.json has a build script, appends \`&& ait build\` to it, and adds a \`deploy\` (\`ait deploy\`) script.
+      - Adds @apps-in-toss/devtools to devDependencies, and finds your vite/webpack/rspack/rollup config file to automatically plug the devtools plugin into its plugins array (shows manual setup instructions if it can't be plugged in automatically).
+      - Adds \`*.ait\` to .gitignore, and installs dependencies with the detected package manager.
+    `,
+	"init.example.interactive.label": "Initialize interactively",
+	"init.example.appName.label": "Initialize with an app name",
+	"init.option.appName": "Sets the app name in kebab-case. If omitted, you're prompted interactively. e.g. my-miniapp",
+	"migration.description": "Automatically converts an @apps-in-toss/web-framework 2.x project to the 3.x config format.",
+	"migration.details": `
+      Selects which migration to run via the target argument. Currently only one target is registered: \`v3\`.
+
+      \`ait migrate v3\` converts granite.config.(ts|js|mjs) to apps-in-toss.config with the same extension.
+
+      - Removes every property under \`brand\` except \`primaryColor\`.
+      - Renames \`webViewProps\` to \`webView\`, and removes the \`type\` property inside it.
+      - Renames \`outdir\` to \`webBundleDir\`.
+      - Moves the \`web.commands.dev\`/\`web.commands.build\` values to the \`dev\`/\`build\` scripts in \`package.json\`, and appends \`&& ait build\` to the end of the \`build\` script.
+      - Adds \`@apps-in-toss/devtools\` to \`devDependencies\`, and finds your vite/webpack/rspack/rollup config file to automatically plug the devtools plugin into its plugins array (shows manual setup instructions if it can't be plugged in automatically).
+      - Once all of the above changes are done, deletes the original granite.config file and runs install with the detected package manager.
+
+      If granite.config can't be found, or web.commands.dev/build isn't a string, nothing is changed and the reason is reported. If the conversion fails partway through, the changes applied so far are automatically rolled back — but once it finishes successfully it can't be rolled back, so we recommend saving your current state (e.g. with a git commit) before running it.
+    `,
+	"migration.example.v3.label": "Migrate to web-framework 3.x",
+	"token.description": "Manages API tokens used for deployment, per profile.",
+	"token.details": `
+      A profile is an API token saved under a name in the ~/.ait/credentials file. Specify \`ait deploy --profile <name>\` to deploy using the token saved for that profile; omit --profile to use the default profile.
+    `,
+	"token.example.add.label": "Add a token",
+	"token.example.remove.label": "Remove a token",
+	"tokenAdd.description": "Adds a secret token. Tokens are stored per profile in ~/.ait/credentials, and can be loaded with ait deploy --profile.",
+	"tokenAdd.example.default.label": "Add a token under the default profile",
+	"tokenAdd.example.profile.label": "Add a token under a named profile",
+	"tokenAdd.example.apiKey.label": "Pass the API key directly as an option",
+	"tokenAdd.option.apiKey": "Sets the token value directly. If omitted, you're prompted interactively.",
+	"tokenRemove.description": "Removes a secret token stored in ~/.ait/credentials.",
+	"tokenRemove.example.default.label": "Remove the default profile's token",
+	"tokenRemove.example.profile.label": "Remove a token by profile name"
+};
+//#endregion
+//#region src/i18n/ko.ts
+const ko = {
+	"groupHelp.commandsHeader": "Commands",
+	"groupHelp.detailHint": "각 명령어 뒤에 -h 또는 --help 옵션을 붙이면 더 자세한 설명을 볼 수 있어요.",
+	"help.unknownPath": "'{path}' 명령어를 찾을 수 없어요.",
+	"help.unknownPath.guide": "사용 가능한 명령어는 아래에서 확인해주세요.",
+	"build.description": "설정 파일(apps-in-toss.config)을 읽어 배포용 .ait 아티팩트를 만들어요.",
+	"build.details": `
+      프로젝트 루트(package.json이 있는 디렉토리)의 apps-in-toss.config.(ts|js|mjs)를 읽어서 .ait 아티팩트를 만들어요. 이 설정 파일이 없으면 실행에 실패해요 — 신규 프로젝트라면 \`ait init\`으로, 기존 granite.config 프로젝트라면 \`ait migrate v3\`로 먼저 만들어주세요.
+
+      apps-in-toss.config의 webBundleDir에 지정한 디렉토리를 그대로 아티팩트에 담기 때문에, 이 명령을 실행하기 전에 웹 프레임워크의 빌드 명령(예: vite build)을 먼저 실행해서 그 디렉토리에 index.html을 포함한 산출물이 있어야 해요.
+
+      완성된 아티팩트는 프로젝트 루트에 \`<appName>.ait\`로 저장되고, \`ait deploy\`가 이 파일을 찾아 업로드해요.
+    `,
+	"build.example.artifact.label": "아티팩트 빌드",
+	"deploy.description": "빌드된 .ait 아티팩트를 앱인토스에 업로드(배포)해요.",
+	"deploy.details": `
+      API 키는 다음 순서로 결정돼요.
+
+      - \`--profile\`로 지정한(또는 지정하지 않았을 때 \`default\`) 프로필에 저장된 토큰이 있으면 그걸 사용해요.
+      - 저장된 토큰이 없으면 \`--api-key\`로 직접 입력한 값을 사용해요.
+      - 둘 다 없으면 대화형 프롬프트로 API 키를 입력받아요.
+
+      프로필에 토큰을 저장해두고 싶다면 \`ait token add\`로 먼저 등록해주세요.
+    `,
+	"deploy.example.default.label": "기본 아티팩트(.ait) 배포",
+	"deploy.example.location.label": "특정 .ait 파일 배포",
+	"deploy.example.profile.label": "프로필에 저장된 토큰으로 배포",
+	"deploy.example.memo.label": "출시 메모와 함께 배포",
+	"deploy.example.memo.cmd": "ait deploy -m \"출시 메모(최대 1000자)\"",
+	"deploy.example.schemeOnly.label": "배포 결과 scheme만 출력",
+	"deploy.option.apiKey": "배포를 위한 API 키예요. 이 옵션으로 직접 입력하거나, --profile 옵션으로 프로필을 지정하면 그 프로필에 등록된 API 키를 사용해요.",
+	"deploy.option.workspace": "(deprecated) 토큰 워크스페이스 이름이에요. 이 옵션 대신 --profile 옵션을 사용해주세요.",
+	"deploy.option.profile": "ait token add 명령어로 ~/.ait/credentials에 등록한 프로필이에요. 프로필이 없으면 default 프로필을 사용해요.",
+	"deploy.option.baseUrl": "배포 API의 base URL을 직접 지정해요. 일반적인 배포에서는 지정할 필요가 없고, 별도 환경을 대상으로 테스트할 때만 사용해요.",
+	"deploy.option.location": "업로드할 .ait 파일의 경로를 명시적으로 지정해요. 지정하지 않으면 현재 패키지 루트 디렉토리에서 발견되는 첫 .ait 파일을 사용해요.",
+	"deploy.option.schemeOnly": "배포 결과를 intoss-private scheme만 출력하도록 설정해요. 기본값은 false예요.",
+	"deploy.option.memo": "출시 메모를 입력해요. 최대 1000자까지 입력할 수 있어요.",
+	"init.description": "기존 웹 프로젝트에 앱인토스 배포에 필요한 설정을 추가해요.",
+	"init.details": `
+      새 프로젝트를 만들지는 않아요 — package.json이 있는 기존 웹 프로젝트(예: Vite로 만든 프로젝트)에서 실행해주세요.
+
+      실행하면 다음을 처리해요.
+
+      - 앱 이름(케밥-케이스)을 물어보고, 웹 번들 결과물 디렉토리를 물어봐요(기본값 dist).
+      - apps-in-toss.config.ts 파일을 생성해요.
+      - package.json에 build 스크립트가 있으면 뒤에 \`&& ait build\`를 붙이고, \`deploy\`(\`ait deploy\`) 스크립트를 추가해요.
+      - devDependencies에 @apps-in-toss/devtools를 추가하고, vite/webpack/rspack/rollup 설정 파일을 찾아 plugins 배열에 devtools 플러그인을 자동으로 꽂아요(자동으로 못 꽂으면 수동 설치 안내를 보여줘요).
+      - .gitignore에 \`*.ait\`를 추가하고, 감지한 패키지 매니저로 의존성을 설치해요.
+    `,
+	"init.example.interactive.label": "대화형으로 초기화",
+	"init.example.appName.label": "앱 이름을 지정하여 초기화",
+	"init.option.appName": "앱 이름을 케밥-케이스로 지정해요. 생략하면 대화형 프롬프트로 입력받아요. 예) my-miniapp",
+	"migration.description": "@apps-in-toss/web-framework 2.x 프로젝트를 3.x 설정 형식으로 자동 변환해요.",
+	"migration.details": `
+      target 인자로 실행할 마이그레이션을 선택해요. 현재 등록된 타깃은 \`v3\` 하나예요.
+
+      \`ait migrate v3\`는 granite.config.(ts|js|mjs)를 같은 확장자의 apps-in-toss.config로 변환해요.
+
+      - \`brand\`에서 \`primaryColor\`를 제외한 나머지 속성은 지워요.
+      - \`webViewProps\`는 \`webView\`로 이름을 바꾸고, 그 안의 \`type\` 속성은 지워요.
+      - \`outdir\`은 \`webBundleDir\`로 이름을 바꿔요.
+      - \`web.commands.dev\`/\`web.commands.build\` 값을 \`package.json\`의 \`dev\`/\`build\` 스크립트로 옮기고, \`build\` 스크립트 끝에 \`&& ait build\`를 붙여요.
+      - \`devDependencies\`에 \`@apps-in-toss/devtools\`를 추가하고, vite/webpack/rspack/rollup 설정 파일을 찾아 plugins 배열에 devtools 플러그인을 자동으로 꽂아요(자동으로 못 꽂으면 수동 설치 안내를 보여줘요).
+      - 위 변경이 모두 끝나면 원본 granite.config 파일을 삭제하고, 감지한 패키지 매니저로 설치를 실행해요.
+
+      granite.config를 찾지 못했거나 web.commands.dev/build가 문자열로 없으면 아무것도 바꾸지 않고 원인을 알려줘요. 변환 도중 실패하면 그때까지 적용한 변경은 자동으로 되돌리지만, 성공적으로 끝난 뒤에는 되돌릴 수 없으니 실행 전에 git commit 등으로 현재 상태를 저장해두는 걸 권장해요.
+    `,
+	"migration.example.v3.label": "web-framework 3.x로 마이그레이션",
+	"token.description": "배포에 사용할 API 토큰을 프로필별로 관리해요.",
+	"token.details": `
+      프로필은 ~/.ait/credentials 파일에 이름으로 구분해서 저장하는 API 토큰이에요. \`ait deploy --profile <이름>\`으로 지정하면 그 프로필에 저장된 토큰을 사용해서 배포하고, --profile을 생략하면 default 프로필을 사용해요.
+    `,
+	"token.example.add.label": "토큰 추가",
+	"token.example.remove.label": "토큰 삭제",
+	"tokenAdd.description": "시크릿 토큰을 추가해요. 토큰은 ~/.ait/credentials에 프로필별로 저장되고, ait deploy --profile로 불러올 수 있어요.",
+	"tokenAdd.example.default.label": "기본 프로필로 토큰 추가",
+	"tokenAdd.example.profile.label": "프로필을 지정하여 토큰 추가",
+	"tokenAdd.example.apiKey.label": "API 키를 옵션으로 직접 전달",
+	"tokenAdd.option.apiKey": "토큰 값을 직접 지정해요. 생략하면 대화형 프롬프트로 입력받아요.",
+	"tokenRemove.description": "~/.ait/credentials에 저장된 시크릿 토큰을 삭제해요.",
+	"tokenRemove.example.default.label": "기본 프로필의 토큰 삭제",
+	"tokenRemove.example.profile.label": "프로필을 지정하여 토큰 삭제"
+};
+//#endregion
+//#region src/i18n/index.ts
+/**
+* i18n for the CLI's --help/usage layer only (command `description`/
+* `details`/`examples`, `Option(...)` `description`). Runtime messages
+* (errors, interactive prompts, progress output, migration logs) are NOT
+* covered by this module and keep using their existing Korean strings
+* directly in the command files.
+*
+* Locale is resolved ONCE per process, at module load time, from
+* `process.env` — not re-detected per call — because clipanion's
+* `Command.Usage()` bakes its strings into static class fields at class
+* definition time, so the active locale has to be known before any command
+* module is evaluated.
+*
+* Locale decision policy (maintainer-confirmed):
+*
+*   1. `AIT_LANG` env var, trimmed and lowercased. If it's `"ko"` or `"en"`,
+*      that value wins outright. Any other value is ignored and falls
+*      through to step 2.
+*   2. Otherwise, check `LC_ALL` → `LC_CTYPE` → `LANG`, in that order, for
+*      the first non-empty value (an empty string counts as unset, per
+*      POSIX convention). If that value's language tag matches `ko`
+*      (`ko`, `ko_KR.UTF-8`, `ko-KR`, ... — anything starting with `ko`
+*      followed by `.`/`_`/`-`/end-of-string), the locale is `ko`.
+*      Everything else (`en_US.UTF-8`, `C`, `POSIX`, ...) resolves to `en`.
+*   3. If all three are empty/unset, the locale is `en`.
+*/
+const KO_LANGUAGE_TAG_RE = /^ko([._-]|$)/i;
+/**
+* Pure decision function — takes `process.env` as an input instead of
+* reading it directly, so the policy above is unit-testable without
+* mutating global process state.
+*/
+function resolveLocale(env) {
+	const override = env.AIT_LANG?.trim().toLowerCase();
+	if (override === "ko" || override === "en") return override;
+	const firstNonEmpty = [
+		env.LC_ALL,
+		env.LC_CTYPE,
+		env.LANG
+	].find((value) => value != null && value !== "");
+	if (firstNonEmpty != null && KO_LANGUAGE_TAG_RE.test(firstNonEmpty)) return "ko";
+	return "en";
+}
+/** The active locale for this process, decided once at module load. */
+const locale = resolveLocale(process.env);
+const tables = {
+	ko,
+	en
+};
+/**
+* Look up a help/usage string for the active locale, with `{name}`
+* placeholder interpolation. Falls back to the key itself if missing, so a
+* forgotten key surfaces visibly rather than rendering empty.
+*/
+function t(key, vars) {
+	const raw = tables[locale][key] ?? key;
+	if (!vars) return raw;
+	return raw.replace(/\{(\w+)\}/g, (match, name) => {
+		const value = vars[name];
+		return value === void 0 ? match : String(value);
+	});
+}
+const HINT_WHEN_ACTIVE_IS_KO = "Set AIT_LANG=en for help in English.";
+const HINT_WHEN_ACTIVE_IS_EN = "AIT_LANG=ko를 설정하면 한국어로 볼 수 있어요.";
+/** The dim cross-locale discovery hint appended to top-level help output. */
+function helpHint() {
+	return locale === "ko" ? HINT_WHEN_ACTIVE_IS_KO : HINT_WHEN_ACTIVE_IS_EN;
+}
+//#endregion
 //#region src/utils/getPackageRoot.ts
 function getPackageRoot(base) {
 	let dirPath = base;
@@ -154,8 +395,9 @@ var BuildCommand = class extends Command {
 	static paths = [["build"]];
 	static usage = Command.Usage({
 		category: "Build",
-		description: "앱인토스 배포용 .ait 아티팩트를 빌드합니다.",
-		examples: [["Build artifact", "apps-in-toss build"]]
+		description: t("build.description"),
+		details: t("build.details"),
+		examples: [[t("build.example.artifact.label"), "ait build"]]
 	});
 	async execute() {
 		const buildResult = await buildArtifact();
@@ -165,14 +407,13 @@ var BuildCommand = class extends Command {
 };
 //#endregion
 //#region src/utils/colors.ts
-function wrap(open, close) {
-	return (input) => `\x1b[${open}m${input}\x1b[${close}m`;
-}
 const colors = {
-	cyan: wrap(36, 39),
-	green: wrap(32, 39),
-	underline: wrap(4, 24)
+	cyan: pc.cyan,
+	dim: pc.dim,
+	green: pc.green,
+	underline: pc.underline
 };
+const isColorSupported = pc.isColorSupported;
 //#endregion
 //#region src/utils/TokenStorage.ts
 var TokenStorage = class TokenStorage {
@@ -343,42 +584,43 @@ var DeployCommand = class extends Command {
 	static paths = [["deploy"]];
 	static usage = Command.Usage({
 		category: "Deploy",
-		description: "빌드된 .ait 아티팩트를 앱인토스에 업로드(배포)합니다.",
+		description: t("deploy.description"),
+		details: t("deploy.details"),
 		examples: [
-			["기본 아티팩트(.ait) 배포", "apps-in-toss deploy"],
-			["특정 .ait 파일 배포", "apps-in-toss deploy --location ./dist/my-app.ait"],
-			["프로필에 저장된 토큰으로 배포", "apps-in-toss deploy --profile dev"],
-			["출시 메모와 함께 배포", "apps-in-toss deploy -m \"출시 메모(최대 1000자)\""],
-			["배포 결과 scheme만 출력", "apps-in-toss deploy --scheme-only"]
+			[t("deploy.example.default.label"), "ait deploy"],
+			[t("deploy.example.location.label"), "ait deploy --location ./dist/my-app.ait"],
+			[t("deploy.example.profile.label"), "ait deploy --profile dev"],
+			[t("deploy.example.memo.label"), t("deploy.example.memo.cmd")],
+			[t("deploy.example.schemeOnly.label"), "ait deploy --scheme-only"]
 		]
 	});
 	apiKey = Option.String("--api-key", {
 		required: false,
-		description: "배포를 위한 API 키입니다. 명시적으로 이 옵션으로 api key를 직접 입력하거나, --profile 옵션을 사용해서 프로필을 지정하면 프로필에 등록된 api key를 사용해요."
+		description: t("deploy.option.apiKey")
 	});
 	workspace = Option.String("--workspace", {
 		required: false,
-		description: "(deprecated) 토큰 워크스페이스 이름입니다. 이 옵션 대신 --profile 옵션을 사용해주세요."
+		description: t("deploy.option.workspace")
 	});
 	profile = Option.String("--profile", {
 		required: false,
-		description: "apps-in-toss token add 명령어를 통해 등록한 프로필이에요. 프로필이 없으면 default 프로필을 사용해요."
+		description: t("deploy.option.profile")
 	});
 	baseUrl = Option.String("--base-url", {
-		description: "API Base URL",
+		description: t("deploy.option.baseUrl"),
 		required: false
 	});
 	location = Option.String("--location", {
-		description: "업로드할 .ait 파일의 경로를 명시적으로 지정해요. 기본값은 현재 패키지 루트 디렉토리에 있는 ait 파일이에요.",
+		description: t("deploy.option.location"),
 		required: false
 	});
 	schemeOnly = Option.Boolean("--scheme-only", {
 		required: false,
-		description: "배포 결과를 intoss-private scheme만 출력하도록 설정해요. 기본값은 false예요."
+		description: t("deploy.option.schemeOnly")
 	});
 	memo = Option.String("-m,--memo", {
 		required: false,
-		description: "출시 메모를 입력해요. 최대 1000자까지 입력할 수 있어요."
+		description: t("deploy.option.memo")
 	});
 	async execute() {
 		const baseUrl = this.baseUrl;
@@ -431,9 +673,12 @@ var DeployCommand = class extends Command {
 		return colors.underline(color(message));
 	}
 	printResult(appName, deploymentId) {
-		const result = `intoss-private://${appName}?_deploymentId=${deploymentId}`;
+		const result = `intoss-private://${appName}?_deploymentId=${deploymentId}&host=appsInTossHost`;
 		if (this.schemeOnly) this.context.stdout.write(`${result}\n`);
-		else p.note(this.decorate(result, colors.green));
+		else {
+			p.log.message(this.decorate(result, colors.green));
+			p.log.message("");
+		}
 	}
 	printError(error) {
 		if (this.schemeOnly) this.context.stdout.write(`${error.message}\n`);
@@ -785,12 +1030,13 @@ var InitCommand = class extends Command {
 	static paths = [["init"]];
 	static usage = Command.Usage({
 		category: "Setup",
-		description: "앱인토스 웹 프레임워크 개발/배포 설정을 초기화합니다.",
-		examples: [["대화형으로 초기화", "apps-in-toss init"], ["앱 이름을 지정하여 초기화", "apps-in-toss init --app-name my-miniapp"]]
+		description: t("init.description"),
+		details: t("init.details"),
+		examples: [[t("init.example.interactive.label"), "ait init"], [t("init.example.appName.label"), "ait init --app-name my-miniapp"]]
 	});
 	appName = Option.String("--app-name", {
 		required: false,
-		description: "앱 이름(케밥-케이스)을 지정해요. 예) my-miniapp"
+		description: t("init.option.appName")
 	});
 	skipInput = Option.Boolean("--skip-input", {
 		required: false,
@@ -1129,8 +1375,9 @@ var MigrationCommand = class extends Command {
 	static paths = [["migrate"]];
 	static usage = Command.Usage({
 		category: "Migration",
-		description: "마이그레이션을 실행해요.",
-		examples: [["Run migration", "apps-in-toss migrate <target>"]]
+		description: t("migration.description"),
+		details: t("migration.details"),
+		examples: [[t("migration.example.v3.label"), "ait migrate v3"]]
 	});
 	target = Option.String({ required: true });
 	async execute() {
@@ -1143,25 +1390,96 @@ var MigrationCommand = class extends Command {
 	}
 };
 //#endregion
+//#region src/utils/groupHelp.ts
+/**
+* Renders a styled "group help" page for a Command whose only job is to
+* gather related subcommands under a shared path prefix (e.g. `ait token`
+* grouping `token add`/`token remove`).
+*
+* Clipanion has no built-in notion of a "subcommand group": a bare group
+* invocation just runs whatever `execute()` the group's own Command defines,
+* and `<group> --help` normally resolves to clipanion's *ambiguous
+* multi-match* help path (every registered command whose path starts with
+* the given prefix) rather than anything group-shaped. This helper is meant
+* to be called from that group Command's own `execute()` instead.
+*
+* It leans on clipanion's own rendering primitives — `cli.usage()` for each
+* subcommand's usage line, `formatMarkdownish` for description text, and
+* `cli.format()` for header/bold styling — so the output stays visually
+* consistent with clipanion's native `--help` pages instead of hand-rolling
+* ANSI output. `cli.format()`/`cli.usage()` already resolve color support
+* the same way the rest of the CLI's help output does, so callers don't need
+* to thread a `colored` flag through.
+*
+* The result always ends with the dim cross-locale discovery hint (see
+* `helpHint()`), so every caller of this helper — the group's own bare
+* invocation (e.g. `ait token`) and the `help` router (`ait help token` /
+* `ait token --help`, rewritten to the same thing by `rewriteHelpArgv`) —
+* automatically renders it without having to append it themselves.
+*/
+function renderGroupHelp(cli, groupUsage, subcommands, labels) {
+	const format = cli.format();
+	let result = ``;
+	if (groupUsage.description) {
+		result += formatMarkdownish(groupUsage.description, {
+			format,
+			paragraphs: false
+		}).replace(/^./, (char) => char.toUpperCase());
+		result += `\n`;
+	}
+	result += `\n`;
+	result += `${format.header(labels.commandsHeader)}\n`;
+	for (const subcommand of subcommands) {
+		result += `\n`;
+		result += cli.usage(subcommand);
+		const description = subcommand.usage?.description;
+		if (description) result += `    ${formatMarkdownish(description, {
+			format,
+			paragraphs: false
+		})}`;
+	}
+	result += `\n`;
+	result += formatMarkdownish(labels.detailHint, {
+		format,
+		paragraphs: true
+	});
+	result += `${colors.dim(helpHint())}\n`;
+	return result;
+}
+//#endregion
 //#region src/commands/token/index.ts
+const tokenUsage = Command.Usage({
+	category: "Auth",
+	description: t("token.description"),
+	details: t("token.details"),
+	examples: [[t("token.example.add.label"), "ait token add <profile?>"], [t("token.example.remove.label"), "ait token remove <profile?>"]]
+});
 var TokenCommand = class extends Command {
 	static paths = [["token"]];
-	static usage = Command.Usage({
-		category: "Auth",
-		description: "토큰 관련 하위 명령을 관리합니다.",
-		examples: [["토큰 추가", "apps-in-toss token add <profile?>"], ["토큰 삭제", "apps-in-toss token remove <profile?>"]]
-	});
-	async execute() {}
+	static usage = tokenUsage;
+	async execute() {
+		this.context.stdout.write(renderGroupHelp(this.cli, tokenUsage, [TokenAddCommand, TokenRemoveCommand], {
+			commandsHeader: t("groupHelp.commandsHeader"),
+			detailHint: t("groupHelp.detailHint")
+		}));
+	}
 };
 var TokenAddCommand = class extends Command {
 	static paths = [["token", "add"]];
 	static usage = Command.Usage({
 		category: "Auth",
-		description: "시크릿 토큰을 추가합니다.",
-		examples: [["기본 별칭으로 토큰 추가", "apps-in-toss token add"], ["별칭을 지정하여 토큰 추가", "apps-in-toss token add dev"]]
+		description: t("tokenAdd.description"),
+		examples: [
+			[t("tokenAdd.example.default.label"), "ait token add"],
+			[t("tokenAdd.example.profile.label"), "ait token add dev"],
+			[t("tokenAdd.example.apiKey.label"), "ait token add dev --api-key <API_KEY>"]
+		]
 	});
 	profile = Option.String({ required: false });
-	apiKey = Option.String("--api-key", { required: false });
+	apiKey = Option.String("--api-key", {
+		required: false,
+		description: t("tokenAdd.option.apiKey")
+	});
 	async execute() {
 		const profile = this.profile || "default";
 		const secret = this.apiKey ? this.apiKey : await p.password({
@@ -1179,8 +1497,8 @@ var TokenRemoveCommand = class extends Command {
 	static paths = [["token", "remove"]];
 	static usage = Command.Usage({
 		category: "Auth",
-		description: "시크릿 토큰을 삭제합니다.",
-		examples: [["기본 워크스페이스의 토큰 삭제", "apps-in-toss token remove"], ["별칭을 지정하여 토큰 삭제", "apps-in-toss token remove dev"]]
+		description: t("tokenRemove.description"),
+		examples: [[t("tokenRemove.example.default.label"), "ait token remove"], [t("tokenRemove.example.profile.label"), "ait token remove dev"]]
 	});
 	profile = Option.String({ required: false });
 	async execute() {
@@ -1190,11 +1508,129 @@ var TokenRemoveCommand = class extends Command {
 	}
 };
 //#endregion
+//#region src/utils/argv.ts
+/**
+* Rewrites any invocation that carries a bare `--help`/`-h` token into
+* `["help", ...path]`, where `path` is the leading run of non-flag tokens
+* that precede it (stopping at the first token that looks like a flag,
+* i.e. starts with `-`).
+*
+* This lets a single registered command (`MainHelpCommand`, see
+* `src/index.ts`) own every help surface instead of relying on clipanion's
+* per-path internal help machinery, which:
+*
+*   - never instantiates a Command for `<command> --help` (it prints usage
+*     directly from inside `Cli#run`, see `Command#help` in clipanion's
+*     `advanced/Command.d.ts`), so that path can't be hooked to append the
+*     cross-locale hint line (see `helpHint()` in `../i18n`).
+*   - resolves `<group> --help` (e.g. `ait token --help`) through its
+*     *ambiguous multi-match* help path whenever the prefix matches more
+*     than one registered command (`token`, `token add`, `token remove`),
+*     printing a generic "Multiple commands match your selection" listing
+*     instead of anything specific to the group.
+*
+* Examples:
+*   `["deploy", "--help"]`                    → `["help", "deploy"]`
+*   `["token", "add", "-h"]`                   → `["help", "token", "add"]`
+*   `["--help"]`                               → `["help"]`
+*   `["token", "--help"]`                      → `["help", "token"]`
+*   `["deploy", "--profile", "x", "--help"]`   → `["help", "deploy"]`
+*     (the path stops at the first flag-like token, `--profile`, even
+*     though that's not the `--help` token itself — everything from there
+*     on is treated as options for whatever command the path names)
+*
+* `-h=<index>` (an explicit index into clipanion's ambiguous-match listing
+* — e.g. `ait token -h=1`) is intentionally left untouched: it never
+* matches the exact-token check below (it's the single string `"-h=1"`,
+* not `"-h"`), so it keeps flowing through clipanion's original internal
+* help machinery unchanged.
+*
+* Argv with no `--help`/`-h` token at all (the common case — an actual
+* command invocation) is returned as a shallow copy, untouched.
+*/
+function rewriteHelpArgv(argv) {
+	if (!argv.some((token) => token === `--help` || token === `-h`)) return [...argv];
+	const path = [];
+	for (const token of argv) {
+		if (token.startsWith(`-`)) break;
+		path.push(token);
+	}
+	return [`help`, ...path];
+}
+//#endregion
 //#region src/index.ts
+const HELP_ROUTES = /* @__PURE__ */ new Map([
+	[`build`, {
+		kind: `leaf`,
+		commandClass: BuildCommand
+	}],
+	[`deploy`, {
+		kind: `leaf`,
+		commandClass: DeployCommand
+	}],
+	[`init`, {
+		kind: `leaf`,
+		commandClass: InitCommand
+	}],
+	[`migrate`, {
+		kind: `leaf`,
+		commandClass: MigrationCommand
+	}],
+	[`token`, {
+		kind: `group`,
+		commandClass: TokenCommand
+	}],
+	[`token add`, {
+		kind: `leaf`,
+		commandClass: TokenAddCommand
+	}],
+	[`token remove`, {
+		kind: `leaf`,
+		commandClass: TokenRemoveCommand
+	}]
+]);
+var MainHelpCommand = class extends Command {
+	static paths = [
+		[`-h`],
+		[`--help`],
+		[`help`]
+	];
+	rest = Option.Rest();
+	async execute() {
+		if (this.rest.length === 0) {
+			this.context.stdout.write(this.cli.usage());
+			this.context.stdout.write(`${colors.dim(helpHint())}\n`);
+			return;
+		}
+		const route = HELP_ROUTES.get(this.rest.join(` `));
+		if (route === void 0) {
+			this.writeUnknownPath(this.rest);
+			return 1;
+		}
+		if (route.kind === `group`) {
+			const command = new route.commandClass();
+			command.context = this.context;
+			command.cli = this.cli;
+			await command.execute();
+			return;
+		}
+		this.context.stdout.write(this.cli.usage(route.commandClass, { detailed: true }));
+		this.context.stdout.write(`${colors.dim(helpHint())}\n`);
+	}
+	writeUnknownPath(path) {
+		const format = this.cli.format();
+		const label = path.join(` `);
+		this.context.stdout.write(`${format.error(`Error`)}: ${t(`help.unknownPath`, { path: label })} ${t(`help.unknownPath.guide`)}\n\n`);
+		this.context.stdout.write(this.cli.usage());
+		this.context.stdout.write(`${colors.dim(helpHint())}\n`);
+	}
+};
 const cli = new Cli({
-	binaryLabel: "appsintoss",
-	binaryName: "appsintoss",
-	enableCapture: true
+	binaryLabel: "Apps in Toss CLI",
+	binaryName: "ait",
+	binaryVersion: "3.1.0",
+	enableCapture: true,
+	enableColors: isColorSupported
 });
 cli.register(BuildCommand);
 cli.register(DeployCommand);
@@ -1203,7 +1639,10 @@ cli.register(MigrationCommand);
 cli.register(TokenCommand);
 cli.register(TokenAddCommand);
 cli.register(TokenRemoveCommand);
-cli.register(Builtins.HelpCommand);
-cli.runExit(process.argv.slice(2));
+cli.register(MainHelpCommand);
+cli.register(Builtins.VersionCommand);
+const rawArgv = process.argv.slice(2);
+const argv = rawArgv.length === 0 ? ["--help"] : rewriteHelpArgv(rawArgv);
+cli.runExit(argv);
 //#endregion
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apps-in-toss/cli",
-  "version": "3.1.0-beta.0",
-  "license": "BSD-3-Clause",
+  "version": "3.1.0",
+  "license": "Apache-2.0",
   "bin": {
     "ait": "dist/index.js"
   },
@@ -23,6 +23,7 @@
     "c12": "3.3.4",
     "clipanion": "^4.0.0-rc.4",
     "jscodeshift": "^17.1.2",
+    "picocolors": "^1.1.1",
     "uuidv7": "^1.2.1"
   },
   "devDependencies": {
@@ -31,4 +32,4 @@
     "tsdown": "0.22.7",
     "typescript": "5.9.3"
   }
-}
+}