# How to Create, Edit, and Utilize Custom Roles for Specialized AI Tasks in nGPT

> Learn to create, edit, and utilize custom roles in nGPT. Developers use --role-config and --role to manage JSON system prompts for specialized AI tasks and reusable personas.

- Repository: [nazDridoy/ngpt](https://github.com/nazdridoy/ngpt)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Developers can create reusable AI personas in nGPT by using the `--role-config` command to manage JSON-based system prompts, then apply them with `--role` to inject specialized behavior into any session.**

nGPT is an open-source CLI tool for interacting with large language models. To help developers maintain consistent AI behavior across different tasks, nGPT supports **custom roles**—persistent system prompts that define specialized personas. This guide explains how to create, edit, and utilize these roles based on the actual implementation in the `nazdridoy/ngpt` repository.

## Understanding nGPT's Custom Role Architecture

The role system in nGPT consists of three integrated components: CLI argument parsing, file-based storage, and runtime prompt injection.

### Role Storage and JSON Structure

Custom roles are stored as individual JSON files in an OS-specific configuration directory. The `get_role_directory()` function in [`ngpt/cli/handlers/role.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/handlers/role.py) (lines 16-35) automatically creates the appropriate path:

- **Linux**: `~/.config/ngpt/ngpt_roles/`
- **macOS**: `~/Library/Application Support/ngpt/ngpt_roles/`
- **Windows**: `%APPDATA%\ngpt\ngpt_roles\`

Each role file follows this JSON structure:

```json
{
  "name": "json_generator",
  "system_prompt": "You are an expert JSON generator. Always respond with valid, well‑formatted JSON based on the user's requirements. Never include explanations or markdown."
}

```

### CLI Integration and Prompt Injection

The `handle_role_config_args` function in [`ngpt/cli/args.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/args.py) (lines 81-85) parses the `--role-config` and `--role` arguments. When a user specifies `--role <name>`, the main entry point in [`ngpt/cli/main.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/main.py) (lines 80-86) calls `get_role_prompt()` to load the stored system prompt and assigns it to `args.preprompt`. This injection happens before any request is sent to the language model, ensuring the AI adopts the specified persona for the entire session.

## Creating and Managing Custom Roles

The role management interface uses the `--role-config` flag followed by a sub-command. The `handle_role_config` function in [`ngpt/cli/handlers/role.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/handlers/role.py) (lines 45-65) implements the dispatcher for these operations.

### Creating a New Role

To create a custom role, use the `create` sub-command with a unique name:

```bash
ngpt --role-config create json_generator

```

This launches an interactive multiline editor where you paste the system prompt. Finish with `Ctrl+D` (or `Ctrl+Z` on Windows). The command validates the input and writes the JSON file to your roles directory.

### Listing and Editing Existing Roles

To view all available roles:

```bash
ngpt --role-config list

```

Output example:

```

Available Roles:
 • json_generator
 • linux_expert
 • code_reviewer

```

To modify an existing role:

```bash
ngpt --role-config edit json_generator

```

The current `system_prompt` pre-loads in the editor. Modify the text and save to update the role definition immediately.

### Removing Roles

To delete a role permanently:

```bash
ngpt --role-config remove json_generator

```

This removes the JSON file from the configuration directory without confirmation, so verify the role name before executing.

## Utilizing Custom Roles in AI Tasks

Once defined, roles integrate seamlessly into standard nGPT workflows through the `--role` parameter.

### Command-Line Usage

Apply a custom role to any query by specifying its name:

```bash
ngpt --role json_generator "Generate a user profile with name, email, address, and preferences"

```

Behind the scenes, [`main.py`](https://github.com/nazdridoy/ngpt/blob/main/main.py) executes `get_role_prompt('json_generator')`, retrieves the stored system prompt, and injects it as `args.preprompt`. The LLM receives the specialized instructions before processing your query, ensuring consistent JSON formatting without requiring repetitive prompt engineering.

You can combine roles with other CLI options:

```bash
ngpt --role linux_expert --temperature 0.2 "Explain how to diagnose high CPU usage"

```

### Programmatic Access

For Python applications building on nGPT, import the role utilities directly:

```python
from ngpt.cli.handlers.role import get_role_prompt

# Load a custom role's system prompt

prompt = get_role_prompt("json_generator")
if prompt:
    print("Loaded role prompt:", prompt)
    # Use this prompt with your API client

```

The `get_role_prompt` function (lines 98-108 in [`role.py`](https://github.com/nazdridoy/ngpt/blob/main/role.py)) handles file path resolution, JSON parsing, and error handling, returning `None` if the role does not exist while printing a friendly warning to stderr.

## Summary

- **Custom roles** in nGPT are JSON files containing `name` and `system_prompt` fields, stored in OS-specific configuration directories.
- Use `--role-config` with sub-commands (`create`, `edit`, `list`, `remove`) to manage roles via [`ngpt/cli/handlers/role.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/handlers/role.py).
- The `get_role_directory()` function ensures cross-platform storage in `~/.config/ngpt/ngpt_roles/` (Linux), `~/Library/Application Support/ngpt/ngpt_roles/` (macOS), or `%APPDATA%\ngpt\ngpt_roles\` (Windows).
- Activate roles during usage with `--role <name>`, which triggers `get_role_prompt()` in [`main.py`](https://github.com/nazdridoy/ngpt/blob/main/main.py) to inject the stored prompt into `args.preprompt`.
- Access roles programmatically by importing `get_role_prompt` from `ngpt.cli.handlers.role`.

## Frequently Asked Questions

### How do I create a custom role that always outputs valid JSON?

Use the `create` sub-command to define a role with strict JSON formatting instructions. Run `ngpt --role-config create json_generator`, then enter a system prompt like: "You are an expert JSON generator. Always respond with valid, well-formatted JSON. Never include explanations or markdown." When you use `ngpt --role json_generator`, every response will follow these constraints without requiring repetitive prompting.

### Where are custom role files stored on my system?

nGPT stores roles in OS-specific configuration directories managed by the `get_role_directory()` function in [`ngpt/cli/handlers/role.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/handlers/role.py). On Linux, roles reside in `~/.config/ngpt/ngpt_roles/`; on macOS, in `~/Library/Application Support/ngpt/ngpt_roles/`; and on Windows, in `%APPDATA%\ngpt\ngpt_roles\`. Each role is a separate JSON file containing the role name and system prompt.

### Can I use custom roles programmatically in Python scripts?

Yes, you can import the role utilities directly from the nGPT package. Import `get_role_prompt` from `ngpt.cli.handlers.role` to load the system prompt string for any stored role. This function handles file resolution, JSON parsing, and error handling, returning the prompt text that you can then pass to your own API client or LLM interface.

### What happens if I specify a role that doesn't exist?

If you use `--role nonexistent_role`, the `get_role_prompt()` function in [`ngpt/cli/handlers/role.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/handlers/role.py) checks the roles directory and finds no matching JSON file. It prints a friendly warning message to stderr indicating the role was not found, and returns `None`. The application continues without injecting a system prompt, effectively falling back to default behavior without the specialized persona.