---
title: role
description: Validate, migrate, and scaffold role repositories
---

`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

| 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. |

## 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 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

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>
```
