gt-access-cli

Lightweight TypeScript CLI for setting up Globe Tracker developer access.

Installation and usage

Install the public npm package:

npm install -g @globetracker/gt-access-cli

The CLI needs an install-specific YAML config file before Kubernetes setup can run. Authorized users receive this file through a private internal channel. Put it at ~/.config/gt-access-cli/config.yaml, or set GT_ACCESS_CLI_CONFIG to an alternate path.

Create the config directory and place the private config file there:

mkdir -p ~/.config/gt-access-cli
# place config.yaml at ~/.config/gt-access-cli/config.yaml

Then run setup:

gt-access-cli setup

For local development, run npm install in the repository and use node ./bin/run.js setup.

For local development, run npm install in the repository and use GT_ACCESS_CLI_CONFIG=/path/to/config.yaml node ./bin/run.js setup.

Troubleshooting configuration

• Config file not found means the private config is missing from the default path and GT_ACCESS_CLI_CONFIG was not set to an existing file.

• Unable to parse config file means the config file is not valid YAML.

• Missing kubernetes.* errors mean the private config file is incomplete.

• kubernetes updates ~/.kube/config after a Keycloak browser login.

• codeartifact uses AWS CLI v2 to retrieve one temporary authorization token and updates recognized npm, Maven, and Gradle credential files that already exist.

• ecr is currently not implemented.

CodeArtifact prerequisites

Before selecting codeartifact:

1. Install AWS CLI v2 and verify aws --version succeeds.
2. Configure AWS credentials with permission to call CodeArtifact. The CLI uses the standard AWS credential chain unless codeartifact.profile is set.
3. Add the codeartifact section to the private runtime config.
4. Run the CLI from the relevant project directory. Missing package-manager files are skipped with warnings rather than treated as setup failures.

The setup runs the equivalent of:

aws codeartifact get-authorization-token \
  --domain <domain> \
  --domain-owner <account-id> \
  --region <region> \
  --query authorizationToken \
  --output text \
  [--profile <aws-profile>]

gt-access-cli captures the token without printing it and checks these existing files:

• <current-directory>/.npmrc: the :_authToken= entry for the exact configured domain, owner, region, and repository endpoint.
• ~/.m2/settings.xml: CodeArtifact Maven <server> passwords using <username>aws</username>, but only when the server ID is referenced by a Maven repository URL for the configured CodeArtifact domain, owner, and region.
• <current-directory>/gradle.properties and ~/.gradle/gradle.properties: CODEARTIFACT_AUTH_TOKEN, codeArtifactToken, or codeArtifactAuthToken properties. Values may use standard token placeholders; comments and other properties are untouched.

Missing files and files without a recognized CodeArtifact entry are not created or rewritten. The CLI reports a warning and continues, so selecting codeartifact no longer fails merely because the current directory has no .npmrc. It performs this recognition pass before requesting a token, and does not call AWS when nothing is eligible. Run setup again after the token expires. If AWS CLI reports missing or expired credentials, refresh the configured AWS login/profile first and retry.

Configuration

The public package does not include real infrastructure values. The private config file supplies Keycloak/OIDC settings and Kubernetes cluster metadata at runtime.

Example config shape with placeholder values:

port: 9999
secret:
  tempLoc: ~/.tmp
codeartifact:
  domain: example-domain
  domainOwner: "123456789012"
  region: eu-west-1
  repository: example-repository
  profile: developer       # optional; otherwise use the AWS credential chain
kubernetes:
  idpIssuerUrl: https://keycloak.example.com/auth
  idpClientId: kubernetes
  idpRealm: example-realm
  userName: keycloak-user
  defaultContext: staging-eks
  clusters:
    - clusterName: arn:aws:eks:region:account:cluster/staging-eks
      contextName: staging-eks
      server: https://example.eks.amazonaws.com
      certificateAuthorityData: LS0t...

Environment variables:

| Variable | Type | Description | Default | Required | |----------|------|-------------|----------|----------| | GT_ACCESS_CLI_CONFIG | string | Path to the private YAML config file | ~/.config/gt-access-cli/config.yaml | | | PORT | number | OAuth callback port override | 9999 | | | SS_TEMP_LOC | string | Temporary file directory override | ~/.tmp | |

Development

npm ci
npm test
npm run typecheck
npm run lint
npm run build
npm run validate

Architecture

• oclif command in src/commands/setup.ts
• Elysia OAuth callback handlers in src/oauth.ts, hosted by a minimal Node HTTP server for CLI runtime compatibility
• kubeconfig merge helpers in src/kubeconfig.ts
• program orchestration in src/program.ts
• AWS CLI CodeArtifact npm/Maven/Gradle credential adapter in src/codeartifact.ts

NestJS is intentionally not used in this rewrite.

AI Development Policy compliance

This repository follows the Globe Tracker AI Development Policy:

• AGENTS.md grounds approved AI assistants in the GT Shared Knowledge Usable workspace and records repository-specific engineering rules.
• .github/workflows/pr-validation.yml runs deterministic TypeScript validation and flowcore-io/usable-pr-validator for human-authored pull requests.
• .github/prompts/pr-validation.md validates CLI architecture, CodeArtifact credential isolation, OWASP Top 10 (2025) risks, tests, documentation, and Usable knowledge capture.
• Significant AI-assisted changes must disclose AI usage, link an enhanced Usable Plan and resulting knowledge where applicable, and receive human review.
• Local opencode.json files are ignored because they can contain AI-provider authentication configuration.

The Usable validator requires these GitHub Actions secrets, preferably supplied at organization scope:

| Secret | Purpose | |--------|---------| | OPENCODE_API_KEY | Authentication for the configured OpenCode AI provider | | USABLE_API_TOKEN | Access to GT Shared Knowledge through Usable MCP |

Comment @usable on an open non-release pull request to request re-validation. Release Please pull requests are intentionally excluded from AI validation, but continue to follow the repository's deterministic release checks.

Release automation

Release Please is configured in manifest mode from the current 2.0.0 release baseline. Future release PRs are generated from conventional commits.

When a Release Please GitHub release is published, .github/workflows/publish.yml validates, builds, packs, and uploads the .tgz artifact to the GitHub release. It does not publish to npm.

Publishing @globetracker/gt-access-cli to npmjs.com is manual:

npm run publish:manual:check
npm run publish:manual
npm run publish:manual:verify

If npm prompts for a one-time password, rerun npm run publish:manual with the OTP flag appended, for example npm run publish:manual -- --otp=123456.