# jackin role (https://jackin.tailrocks.com/commands/role/)



`jackin role` is the local role-authoring command family. Use it when you are building or maintaining a role repository from your desktop.

These commands are for desktop/operator workflows. CI, validation workflows, and future Renovate-style migration automation should keep using the small standalone `jackin-role` binary so role repositories do not need the full `jackin` operator CLI just to validate or migrate their manifest.

## Commands [#commands]

| Command                                                              | What it does                                                                                                                                        |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jackin role validate [<role-repo-path>]`                            | Checks the role manifest, Dockerfile, hooks, environment declarations, and agent table consistency. Defaults to the current directory.              |
| `jackin role migrate [<role-repo-path>]`                             | Updates the role manifest to the current schema version, then validates the repository. Defaults to the current directory.                          |
| `jackin role create <role-name-or-namespace/name> [<projects-dir>]`  | Creates a starter role repository named `jackin-<role-name>`. When `<projects-dir>` is omitted, jackin❯ uses `JACKIN_PROJECTS_DIR` or `~/Projects`. |
| `jackin role construct-version [<role-repo-path>]`                   | Prints the construct image version tag pinned in the role Dockerfile. Defaults to the current directory.                                            |
| `jackin role published-image [<role-repo-path>]`                     | Prints the published Docker image declared in the role manifest. Defaults to the current directory.                                                 |
| `jackin role published-image-repository [<role-repo-path>]`          | Prints the published Docker image repository without its tag or digest. Defaults to the current directory.                                          |
| `jackin role publish-labels --role-git-sha <sha> [<role-repo-path>]` | Prints the OCI labels required when publishing a role image. Defaults to the current directory.                                                     |

## Create a role [#create-a-role]

Create writes a small valid role repository with a manifest, Dockerfile, README, ignore files, and a GitHub Actions validation workflow:

```sh
jackin role create ChainArgos/Backend-Engineer "$HOME/Projects"
cd "$HOME/Projects/chainargos/jackin-backend-engineer"
jackin role validate .
```

jackin❯ lowercases the role selector before it creates directories or writes scaffold references. For example, `ChainArgos/Backend-Engineer` becomes `chainargos/backend-engineer`, and the repository directory is `$HOME/Projects/chainargos/jackin-backend-engineer`.

The scaffold is intentionally small. You still own the Dockerfile, manifest, README, and Git history. After reviewing the generated files, initialize the repository and publish it where the selector points:

```sh
git init
git branch -M main
git add -A
git commit -m "Initial role setup"
gh repo create chainargos/jackin-backend-engineer --source=. --remote=origin --push
```

Then load it like any other namespaced role:

```sh
jackin load chainargos/backend-engineer . --debug
```

## Validate a role [#validate-a-role]

Validate before pushing role changes:

```sh
jackin role validate .
```

Validation checks the role manifest, Dockerfile, hook paths, environment declarations, and agent table consistency. It uses the same role-repo contract as the standalone validator.

## Migrate a manifest [#migrate-a-manifest]

When jackin❯ reports that a role manifest needs a newer schema version, run the local migration command from your checkout or pass the role repository path:

```sh
jackin role migrate <role-repo-path>
```

The command rewrites the role manifest in that repository and then validates the result. Inspect the diff, commit it in the role repository, and push it like any other role change.

In CI or automation, use the standalone equivalent instead:

```sh
jackin-role migrate <role-repo-path>
```

## Publish metadata for CI [#publish-metadata-for-ci]

The standalone `jackin-role` binary exposes the role-image metadata that reusable workflows and custom CI need when publishing a role image:

```sh
jackin-role published-image-repository .
jackin-role publish-labels --role-git-sha "$(git rev-parse HEAD)" .
```

`published-image-repository` prints the `published_image` repository without a tag or digest. `publish-labels` prints the canonical Docker label lines, including `jackin.construct.version` from the role Dockerfile and `jackin.role.git.sha` from the SHA passed by CI.