Metadata-Version: 2.5
Name: iagent-skill-hub
Version: 0.1.0
Summary: Python CLI for mushroomAgentHub skills
Project-URL: Homepage, https://github.com/kiwi-data/mushroomAgentHub
Project-URL: Repository, https://github.com/kiwi-data/mushroomAgentHub
Project-URL: Issues, https://github.com/kiwi-data/mushroomAgentHub/issues
Keywords: cli,mushroom-agent-hub,skills
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# iagent-skill-hub

Requires Python 3.11 or newer. The CLI uses only the Python standard library at runtime.

Install from this repository:

```bash
python3.11 -m pip install ./cli
iagent-skill-hub --help
```

Or run without installing:

```bash
PYTHONPATH=cli python3.11 -m iagent_skill_hub.cli --help
```

The default API is `https://skillshub.kiwilightyear.com/api/v1`. Set `IAGENT_SKILL_HUB_API_BASE` or pass `--api-base` before the command to use another API. Protected commands use a Pearl access token from `IAGENT_SKILL_HUB_TOKEN` or `--token`. The previous `MUSHROOM_HUB_*` environment variables also work. The backend accepts the token in `Authorization: Bearer ...`; a browser GitHub session cookie cannot be used as a CLI token.

```bash
export IAGENT_SKILL_HUB_API_BASE=http://127.0.0.1:8000/api/v1
export IAGENT_SKILL_HUB_TOKEN=<your-pearl-access-token>

iagent-skill-hub list --query markdown --sort-by stars
iagent-skill-hub info example-skill
iagent-skill-hub files example-skill
iagent-skill-hub versions example-skill
iagent-skill-hub cat example-skill SKILL.md
iagent-skill-hub download example-skill --version 1.0.0 --output example.zip
iagent-skill-hub install example-skill
iagent-skill-hub install example-skill --dir ./skills/example-skill --force
iagent-skill-hub uninstall example-skill

iagent-skill-hub publish example-skill --dir ./my-skill --name "Example Skill" \
  --version 1.0.0 --changelog "Initial release" --tag tools
iagent-skill-hub edit example-skill --dir ./my-skill --name "Example Skill" \
  --version 1.1.0 --changelog "Add examples"
iagent-skill-hub edit example-skill --name "Example Skill" \
  --version 1.1.0 --changelog "Update metadata"
iagent-skill-hub delete example-skill

iagent-skill-hub stars example-skill
iagent-skill-hub star example-skill
iagent-skill-hub unstar example-skill
iagent-skill-hub starred
iagent-skill-hub comments example-skill
iagent-skill-hub comment example-skill "Helpful skill"
```

`publish` uploads every file below `--dir` through the backend's presigned URL API, then publishes the manifest. `edit` with `--dir` replaces the version's file set; omitting `--dir` keeps the existing files. The directory must contain a nonempty `SKILL.md`. `install` extracts an archive under `~/.mushroom-agent-hub/skills/<slug>` by default and refuses to replace an existing directory unless `--force` is given.

Run tests with `python3.11 -m unittest discover -s cli/tests -v` from the repository root.

## Publish to the internal Python package registry

To publish directly from your machine, use the local script from the repository root (it also works from another directory):

```bash
./cli/publish-internal.sh --dry-run
./cli/publish-internal.sh
```

The script needs `uv`, runs the CLI tests, builds an isolated wheel and source archive, checks them with Twine, and then uploads them to the internal registry. Twine prompts for the `internal` account password unless `TWINE_PASSWORD` is already set. Change `version` in `cli/pyproject.toml` before publishing a new release.

The GitHub Actions workflow `.github/workflows/publish-python-cli-to-internal-pypi.yml` builds, tests, checks, and uploads the package to `https://pypi.kiwilightyear.com/internal/prod/` when a tag such as `iagent-skill-hub-v0.1.0` is pushed. The tag version must match `cli/pyproject.toml`. Increment the version for each new release.

Before releasing, create a GitHub environment named `internal-pypi` and add its secret `INTERNAL_PYPI_PASSWORD` with the password for the `internal` account. The workflow passes that account and secret separately to the upload action; do not put credentials in the repository URL. The runner must be able to reach the internal registry.

For installation after release, use the registry's **Simple API index URL** with pip or uv. That URL may differ from the upload endpoint above; get the install URL and read credentials from your registry administrator. Keep credentials out of the command history where possible.

After merging the package and workflow, publish a matching tag:

```bash
git tag iagent-skill-hub-v0.1.0
git push origin iagent-skill-hub-v0.1.0
```

## Publish to public PyPI from your machine

Use a PyPI API token for the `iagent-skill-hub` project. For the first release, the token needs permission to create the project. The script prompts for the token unless `TWINE_PASSWORD` is set; do not put it in the repository or a command-line argument.

```bash
./cli/publish-pypi.sh --dry-run
./cli/publish-pypi.sh
```

This uploads to `https://upload.pypi.org/legacy/` with username `__token__`. After publishing, install with `python3.11 -m pip install iagent-skill-hub`. Increment `cli/pyproject.toml`'s version before publishing another release.
