@grantjs/cli

中文文档
1.29.0发布于 2026/11/10MITTypeScriptES Module构建来源已验证近 30 天下载 5388

Grant CLI — profiles, REST API, and typings generation

原始使用文档
文档目录11 节
  1. Install
  2. Commands overview
  3. Setup: grant start
  4. Session authentication
  5. Generate types: grant generate-types
  6. Config: grant config
  7. grant config path
  8. grant config list
  9. grant config show
  10. grant config set
  11. Development (from monorepo)

@grantjs/cli

Grant CLI for profiles, REST API access, and typings generation. Agents and scripts should use grant api or grant <resource> <verb> with --output json (or GRANT_* environment variables).

Install

pnpm add -g @grantjs/cli
# or
npm install -g @grantjs/cli

Commands overview

CommandDescription
grant versionShow CLI version (-j, --json for JSON)
grant help / grant --helpShow help
grant startInteractive setup (API URL, auth, profile, scope); alias: grant setup
grant whoamiShow the authenticated caller (GET /api/me)
grant api <method> <path>Call any REST path with the resolved profile
grant <resource> <verb>Named REST commands from OpenAPI (e.g. grant users list)
grant generate-typesGenerate project-scoped ResourceSlug and ResourceAction TypeScript (uses selected profile)
grant config pathPrint path to the config file
grant config listList profiles and which is default
grant config showShow config summary for a profile (no secrets)
grant config set <key>Set a config value for a profile (see below)

All commands that use config accept -p, --profile <name> (or GRANT_PROFILE). API commands also accept --output json|text (JSON when stdout is not a TTY).

Environment: GRANT_API_URL, GRANT_ACCESS_TOKEN, GRANT_CLIENT_ID, GRANT_CLIENT_SECRET, GRANT_SCOPE_TENANT, GRANT_SCOPE_ID, GRANT_ORIGIN_VERIFY. Flags win over env, env over the profile file.

export GRANT_PROFILE=ci
grant whoami --output json
grant users list --output json
grant api post /api/roles --body '{"name":"Reviewer"}'

Setup: grant start

Interactive flow:

  1. Grant API base URL – Default: http://localhost:4000 (or existing value).
  2. Authentication method – Session (browser login) or API key.
  3. Profile name – Name for this config (e.g. default, staging). Override with --profile <name> to skip the prompt.
  4. Session flow – Sign in with Email (email + password) or GitHub (browser OAuth). Then choose account → organization (if applicable) → project.
  5. API key flow – Client ID (UUID), client secret (min 32 chars), scope tenant (accountProject / organizationProject), scope ID (e.g. accountId:projectId or organizationId:projectId).
  6. Default output for generate-types – Optional path (e.g. ./src/grant-types.ts). Leave empty for ./grant-types.ts.

Config is saved to the platform config dir (e.g. ~/.config/grant/config.json on Linux/macOS). The first profile created becomes the default; change it with grant config set default-profile <name>.

Session authentication

  • Email – You are prompted for email and password; the CLI calls the Grant API login endpoint and stores the returned access and refresh tokens.
  • GitHub – The CLI starts a temporary local HTTP server and opens your browser to the Grant API’s GitHub OAuth URL with a redirect to http://localhost:<port>. After you sign in with GitHub, the API redirects back to that URL with a one-time code. The CLI exchanges the code for access and refresh tokens via POST /api/auth/cli-callback. No tokens are sent in the URL; the code is single-use and short-lived (e.g. 60 seconds). The API only accepts localhost (or 127.0.0.1) as the redirect for this flow.

Examples:

grant start
grant start --profile staging

Generate types: grant generate-types

Loads the selected profile, exchanges API key for a token if needed, fetches resources and permissions for the project scope, and writes a TypeScript file with ResourceSlug and ResourceAction constants.

  • -o, --output <path> – Output file (default: profile’s generateTypesOutputPath or ./grant-types.ts).
  • --dry-run – Print what would be generated without writing.
  • -p, --profile <name> – Profile to use (default: default profile).

Examples:

grant generate-types
grant generate-types --profile staging -o ./src/grant-types.ts
grant generate-types --dry-run

Config: grant config

grant config path

Prints the path to the config file (no profile).

grant config list

Lists profile names and marks the default.

grant config show

Shows config summary for a profile (API URL, auth method, scope, generate-types output; no secrets).

  • -p, --profile <name> – Profile to show (default: default profile).

grant config set

Set a value for a profile. Use -p, --profile <name> to target a profile (default: default profile).

SubcommandDescription
grant config set api-url <url>Set Grant API base URL (e.g. http://localhost:4000)
grant config set auth-method <session | api-key>Set authentication method
grant config set credentialsSet API key and scope (see options below)
grant config set scopeSet selected project scope only
grant config set generate-types-output <path>Set default output path for grant generate-types (empty to clear)
grant config set origin-verify [secret]Set x-origin-verify when apiUrl is the raw API origin
grant config set default-profile <name>Set which profile is used when --profile is omitted

Credentials options (all required for credentials):

  • --client-id <id> – API key client ID (UUID)
  • --client-secret <secret> – API key client secret (min 32 characters)
  • --scope-tenant <tenant> – accountProject or organizationProject
  • --scope-id <id> – e.g. accountId:projectId or organizationId:projectId

Scope options (for scope):

  • --tenant <tenant> – accountProject or organizationProject
  • --scope-id <id> – Scope ID string

Examples:

grant config set api-url http://localhost:4000
grant config set api-url http://localhost:4000 --profile staging
grant config set credentials --client-id <uuid> --client-secret <secret> --scope-tenant organizationProject --scope-id <orgId>:<projectId>
grant config set scope --tenant organizationProject --scope-id <orgId>:<projectId>
grant config set generate-types-output ./src/grant-types.ts
grant config set default-profile staging

Development (from monorepo)

pnpm --filter @grantjs/cli run build
node packages/@grantjs/cli/dist/index.mjs version
# or link globally: from packages/@grantjs/cli run pnpm link --global

Interactive TUI: Run grant start (and any prompts) in a real terminal so the process has a TTY. Running via IDE "Run" or in CI often has no stdin and prompts will not work.

Documentation: Grant CLI in the official docs.

Publishing: See RELEASE.md for versioning and npm publish (Changesets).

Tests:

pnpm --filter @grantjs/cli test
pnpm --filter @grantjs/cli test:watch

版本与发布记录

@grantjs/cli 共发布 70 个版本,首次发布于 2026/03/12;过去 12 个月发布了 70 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.29.0latest2026/11/106 天前
1.28.02026/11/098 天前
1.27.12026/11/098 天前
1.27.02026/11/098 天前
1.26.02026/11/0710 天前
1.25.12026/11/0610 天前

关于 @grantjs/cli 的常见问题

@grantjs/cli 是什么?

Grant CLI — profiles, REST API, and typings generation

如何安装 @grantjs/cli?

在项目目录运行 npm install @grantjs/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 grant,可以用 npx grant 直接运行。

@grantjs/cli 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grantjs/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@grantjs/cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@grantjs/cli 可以商用吗?

@grantjs/cli 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@grantjs/cli 的下载量有多少?

根据 npm 官方下载统计,@grantjs/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,388 次,日均约 180 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grantjs/cli 还在维护吗?

最新版本 1.29.0 发布于 2026/11/10(6 天前);至今共发布 70 个版本,其中过去 12 个月发布了 70 个;首次发布于 2026/03/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。