asdf-ghjk

[](https://github.com/Hyperpolymath/asdf-ghjk/actions/workflows/ci.yml)

[ghjk](https://github.com/metatypedev/ghjk) plugin for the [asdf version manager](https://asdf-vm.com).

Contents

• [Dependencies](#dependencies)

• [Installation](#installation)

• [Usage](#usage)

• [Configuration](#configuration)

• [Troubleshooting](#troubleshooting)

• [Contributing](#contributing)

• [License](#license)

What is ghjk?

ghjk is a modern development environment manager and successor to asdf. It provides:

• Unified package management across npm, PyPI, crates.io, and more

• TypeScript-based task automation powered by Deno

• Reproducible POSIX environments for development, CI/CD, and containers

• Declarative configuration with environment inheritance

For more details, visit the [ghjk repository](https://github.com/metatypedev/ghjk).

Dependencies

Required

• bash - Shell interpreter

• curl - For downloading releases

• tar - For extracting archives

• sort, grep - For version parsing

ghjk Runtime Dependencies

Once installed, ghjk requires these tools to function:

• git - Version control

• curl - HTTP requests

• tar - Archive extraction (GNU tar recommended)

• unzip - ZIP archive extraction

• zstd - Compression tool

The install script will check for these and warn if any are missing.

Installation

asdf Plugin

= Add the plugin

asdf plugin add ghjk https://github.com/Hyperpolymath/asdf-ghjk.git

= List all available versions

asdf list all ghjk

= Install a specific version

asdf install ghjk latest

= Set global version

asdf global ghjk latest

= Or set local version for a project

asdf local ghjk 0.3.2

Verify Installation

= Check installed version

ghjk --version

= Run ghjk help

ghjk --help

Usage

Installing Versions

= Install latest version

asdf install ghjk latest

= Install specific version

asdf install ghjk 0.3.2

= Install latest from minor version

asdf install ghjk 0.3

= Install and set as global default

asdf install ghjk latest && asdf global ghjk latest

Version Management

= List installed versions

asdf list ghjk

= List all available versions

asdf list all ghjk

= Show current version

asdf current ghjk

= Uninstall a version

asdf uninstall ghjk 0.3.1

= Set version for current shell session

asdf shell ghjk 0.3.2

Using ghjk

Once installed, initialize a project:

= Initialize with TypeScript support

ghjk init ts

= This creates a ghjk.ts configuration file

Example ghjk.ts configuration:

// ghjk.ts - Development environment configuration
export { sophon } from "https://deno.land/x/ghjk/mod.ts";

sophon({
  // Define environment variables
  env: {
    DATABASE_URL: "postgresql://localhost/myapp",
  },

  // Install tools and runtimes
  installs: [
    { name: "node", version: "20.0.0" },
    { name: "python", version: "3.11" },
  ],

  // Define tasks
  tasks: {
    dev: "npm run dev",
    test: "pytest tests/",
    build: "npm run build",
  },
});

Activate the environment:

= Load the ghjk environment

ghjk env

= Or use ghjk to run commands in the environment

ghjk run dev
ghjk run test

Configuration

Environment Variables

GITHUB_API_TOKEN

Set this to avoid GitHub API rate limits (especially useful in CI):

export GITHUB_API_TOKEN="ghp_your_token_here"

Create a token at [GitHub Settings > Tokens](https://github.com/settings/tokens). No special permissions needed for public repositories.

.tool-versions Example

= .tool-versions - asdf configuration

ghjk 0.3.2
nodejs 20.0.0
python 3.11.0

Platform Support

This plugin supports the same platforms as ghjk:

| Platform | Architecture | Status | |----------|-------------|---------| | Linux | x86_64 | ✅ Supported | | Linux | aarch64 | ✅ Supported | | macOS | x86_64 | ✅ Supported | | macOS | arm64 (M1+) | ✅ Supported |

Troubleshooting

Common Issues

Rate Limit Exceeded

Error: GitHub API rate limit exceeded

Solution: Set GITHUB_API_TOKEN environment variable:

= In your shell profile (~/.bashrc, ~/.zshrc, etc.)

export GITHUB_API_TOKEN="ghp_your_token_here"

Download Failures

Error: Failed to download after 3 attempts

Solution: Check your internet connection and GitHub status. The plugin automatically retries with exponential backoff.

Platform Not Supported

Error: Unsupported operating system or Unsupported architecture

Solution: Check that your platform is supported. Run:

uname -s  # Should be Linux or Darwin
uname -m  # Should be x86_64, aarch64, or arm64

Missing Runtime Dependencies

Warning: Missing recommended runtime dependencies: git tar curl unzip zstd

Solution: Install the missing tools:

= Ubuntu/Debian

sudo apt-get install git tar curl unzip zstd

= macOS

brew install git tar curl unzip zstd

= Fedora/RHEL

sudo dnf install git tar curl unzip zstd

Checksum Verification Failed

Error: Checksum verification failed

Solution: This indicates a corrupted download. Remove the download and try again:

= Remove cached downloads

rm -rf ~/.asdf/downloads/ghjk

= Reinstall

asdf install ghjk <version>

Debug Mode

Enable verbose output:

= Enable asdf debug mode

export ASDF_DEBUG=1

= Try the operation again

asdf install ghjk latest

Getting Help

1. Check the [ghjk documentation](https://github.com/metatypedev/ghjk)

2. Check the [asdf documentation](https://asdf-vm.com)

3. Search [existing issues](https://github.com/Hyperpolymath/asdf-ghjk/issues)

4. Open a [new issue](https://github.com/Hyperpolymath/asdf-ghjk/issues/new)

Development

Testing Locally

= Clone the repository

git clone https://github.com/Hyperpolymath/asdf-ghjk.git
cd asdf-ghjk

= Test list-all

./bin/list-all

= Test download (requires environment variables)

export ASDF_INSTALL_VERSION="0.3.2"
export ASDF_DOWNLOAD_PATH="/tmp/asdf-ghjk-test"
export ASDF_INSTALL_PATH="/tmp/asdf-ghjk-install"

./bin/download
./bin/install

= Verify installation

/tmp/asdf-ghjk-install/bin/ghjk --version

Running Tests

= Install BATS testing framework

git clone https://github.com/bats-core/bats-core.git test/bats

= Run tests

./test/bats/bin/bats test/

Linting

= Install ShellCheck

= Ubuntu/Debian: apt-get install shellcheck

= macOS: brew install shellcheck

= Run linting

shellcheck bin/* lib/*.sh

Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Quick Start

1. Fork the repository

2. Create a feature branch: git checkout -b feature/my-feature

3. Make your changes

4. Run tests and linting

5. Commit: git commit -am 'Add new feature'

6. Push: git push origin feature/my-feature

7. Open a Pull Request

License

See [LICENSE](LICENSE) file for details.

Related Projects

• [ghjk](https://github.com/metatypedev/ghjk) - The tool this plugin installs

• [asdf](https://asdf-vm.com) - Version manager framework

• [asdf-plugins](https://github.com/asdf-vm/asdf-plugins) - Official plugin registry

Credits

• Developed by the asdf-ghjk maintainers

• Built on the [asdf plugin template](https://github.com/asdf-vm/asdf-plugin-template)

• Supports [ghjk](https://github.com/metatypedev/ghjk) by Metatype

---

Note: This is an unofficial plugin. For official ghjk support, refer to the [ghjk repository](https://github.com/metatypedev/ghjk).