getpkg/README.md

getpkg - Package Manager for Dropshell Tools

getpkg is a command-line package manager that simplifies tool installation, management, and publishing for the dropshell ecosystem. Tools are installed to ~/.local/bin/getpkg/ and automatically added to your PATH with bash completion.

Installation

Install getpkg with a single command:

curl https://getbin.xyz/getpkg-install | bash

After installation, restart your shell or run source ~/.bashrc to enable the new PATH and completion settings.

Basic Usage

Installing Tools

Install any tool from the getpkg registry:

# Install a tool
getpkg install ripgrep

# Shorthand syntax (same as above)
getpkg ripgrep

Managing Installed Tools

# List all available commands
getpkg help

# Update all installed tools
getpkg update

# Uninstall a tool
getpkg uninstall ripgrep

# Check getpkg version
getpkg version

Available Commands

Core Package Management

• getpkg <tool_name> - Install or update a tool (shorthand)
• getpkg install <tool_name> - Install or update a tool (explicit)
• getpkg uninstall <tool_name> - Remove an installed tool
• getpkg update - Update getpkg and all installed tools

Publishing (Requires SOS_WRITE_TOKEN)

• getpkg publish <tool_name[:ARCH]> <folder> - Upload a tool to getpkg.xyz
• getpkg unpublish <tool_name[:ARCH]> - Remove a published tool
• getpkg unpublish <hash> - Remove a published tool by hash

Development Tools

• getpkg create <tool_name> <directory> - Create a new tool project
• getpkg hash <file_or_directory> - Calculate hash of files/directories

Information

• getpkg version - Show getpkg version
• getpkg help - Show detailed help
• getpkg autocomplete - Show available commands for completion

How It Works

Installation Process

When you install a tool, getpkg:

1. Downloads the tool archive from getpkg.xyz
2. Extracts it to ~/.local/bin/getpkg/<tool_name>/
3. Updates PATH by modifying ~/.bashrc_getpkg
4. Enables completion for the tool
5. Runs setup if a setup_script.sh exists
6. Stores metadata in ~/.config/getpkg/<tool_name>.json

Architecture Support

getpkg supports multiple architectures:

• x86_64 (Intel/AMD 64-bit)
• aarch64 (ARM 64-bit)
• universal (cross-platform tools)

Tools are automatically downloaded for your architecture, with fallback to universal versions.

File Locations

• Installed tools: ~/.local/bin/getpkg/<tool_name>/
• Configuration: ~/.config/getpkg/
• PATH setup: ~/.bashrc_getpkg (sourced by ~/.bashrc)

Examples

Installing Popular Tools

# Install development tools
getpkg ripgrep        # Fast grep alternative
getpkg fd             # Fast find alternative
getpkg bat            # Cat with syntax highlighting

# Install system utilities
getpkg whatsdirty     # Check git repo status
getpkg sos            # Simple object storage client

Publishing Your Own Tools

# Set your publishing token
export SOS_WRITE_TOKEN="your-token-here"

# Create a new tool project
getpkg create mytool ./mytool-project

# Publish architecture-specific build
getpkg publish mytool:x86_64 ./build/

# Publish universal tool
getpkg publish mytool ./build/

# Remove published tool
getpkg unpublish mytool:x86_64

Development Workflow

# Create tool structure
getpkg create awesome-tool ./awesome-tool
cd awesome-tool

# Build your tool...
# Add executable to the directory

# Test locally
./awesome-tool --version

# Publish when ready
getpkg publish awesome-tool:x86_64 .

Environment Variables

• SOS_WRITE_TOKEN - Authentication token for publishing tools

Troubleshooting

Tool Not Found

If a tool isn't found after installation, ensure your shell has loaded the new PATH:

source ~/.bashrc

Permission Issues

getpkg installs to your home directory and doesn't require root access. If you encounter permission issues, check that ~/.local/bin/ is writable.

Network Issues

All tools are downloaded from getpkg.xyz. Ensure you have internet connectivity and the domain is accessible.

Development

Building getpkg

# Build debug version
cd getpkg && ./build.sh

# Run tests  
cd getpkg && ./test.sh

# Publish (requires SOS_WRITE_TOKEN)
cd getpkg && ./publish.sh

Tool Development

When creating tools for getpkg:

1. Create a directory with your tool binary
2. Optionally include a setup_script.sh for post-install setup
3. The tool should support version and autocomplete subcommands
4. Use getpkg publish to upload to the registry

For more details, see the development documentation in each tool's directory.