# Command-Line Arguments for the OpenAI Plugin Creator Script: Complete Reference

> Master the OpenAI plugin creator script with this complete reference. Learn about essential command-line arguments like plugin_name, path, with-skills, with-marketplace, and force to build your plugins efficiently.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-06-24

---

**The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script accepts a positional `plugin_name` argument plus optional flags—including `--path`, `--with-skills`, `--with-marketplace`, and `--force`—to scaffold new plugin directories and manage Marketplace metadata.**

The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) utility in the openai/plugins repository automates the scaffolding of plugin directories and optional Marketplace manifest updates. Located at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py), this script defines all command-line arguments within the `parse_args` function using Python’s standard `argparse` library. Understanding these arguments allows developers to quickly bootstrap plugins with the correct structure and metadata configuration.

## Required Arguments

### plugin_name (Positional)

The only required argument is the **plugin name**, which is passed as a positional argument. According to lines 86–90 of [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py), this name is automatically normalized to lower-case hyphen-case before being used as the folder name. For example, passing `MyAwesomePlugin` creates a directory named `my-awesome-plugin`.

## Directory Structure Options

### --path

Specifies the parent directory where the plugin folder will be created. As implemented in lines 92–98, this defaults to `<home>/plugins`. For repository-wide plugins, use `<repo>/plugins` to keep the scaffold within the current project structure.

### --with-skills

Creates an empty `skills/` directory under the plugin root. This is defined at lines 99–101 and defaults to **False**.

### --with-hooks

Creates an empty `hooks/` directory for lifecycle scripts, as specified in lines 102–104.

### --with-scripts

Creates an empty `scripts/` directory for utility automation, defined in lines 105–107.

### --with-assets

Creates an empty `assets/` directory intended for icons, screenshots, and other static files. This flag is implemented at lines 108–110.

## Configuration File Scaffolds

### --with-mcp

Adds a placeholder [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file containing MCP server configuration. This option is handled at lines 111–113.

### --with-apps

Adds a placeholder [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file for app definitions, as defined in lines 114–116.

## Marketplace Integration Arguments

### --with-marketplace

Updates or creates the Marketplace manifest ([`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json)). According to lines 117–123, the entry always points to `./plugins/<plugin-name>` relative to the marketplace root. This flag defaults to **False**.

### --marketplace-path

Specifies the path to the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file that should be edited. Lines 124–131 define this to default to `<home>/.agents/plugins/marketplace.json`, allowing you to target repository-specific manifests when needed.

### --install-policy

Sets the Marketplace installation policy. Valid options are `NOT_AVAILABLE`, `AVAILABLE`, or `INSTALLED_BY_DEFAULT`, with the default being `AVAILABLE` as defined in lines 132–136.

### --auth-policy

Sets the Marketplace authentication policy. Options include `ON_INSTALL` or `ON_USE`, defaulting to `ON_USE` according to lines 137–141.

### --category

Specifies the Marketplace category for the plugin. Lines 142–146 set the default value to `Productivity`, though this can be overridden to any custom category string.

## File Overwrite Control

### --force

Forces overwriting of existing files—such as [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) or [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json)—without prompting for confirmation. This safety override is implemented at lines 147–148 and defaults to **False**.

## Practical Usage Examples

Create a basic scaffold in the default plugins directory:

```bash
python3 create_basic_plugin.py my-awesome-plugin

```

Scaffold with optional directories for skills, assets, and scripts:

```bash
python3 create_basic_plugin.py my-awesome-plugin \
    --with-skills --with-assets --with-scripts

```

Add placeholder MCP and app definition files:

```bash
python3 create_basic_plugin.py my-awesome-plugin \
    --with-mcp --with-apps

```

Update the local marketplace manifest with custom metadata:

```bash
python3 create_basic_plugin.py my-awesome-plugin \
    --with-marketplace \
    --category "Developer Tools" \
    --install-policy AVAILABLE \
    --auth-policy ON_USE

```

Use a custom marketplace file and force overwrite of existing entries:

```bash
python3 create_basic_plugin.py my-awesome-plugin \
    --with-marketplace \
    --marketplace-path ./plugins/.agents/plugins/marketplace.json \
    --force

```

## Summary

- The `parse_args` function in [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) defines all CLI arguments between lines 86 and 148.
- **Required**: Only `plugin_name` is mandatory; all other arguments are optional and default to **False** or pre-defined string values.
- **Path control**: Use `--path` to change the scaffold location from `<home>/plugins` to a custom directory.
- **Structure flags**: `--with-skills`, `--with-hooks`, `--with-scripts`, and `--with-assets` create empty subdirectories for organization.
- **Configuration files**: `--with-mcp` and `--with-apps` generate JSON placeholders for MCP servers and app definitions.
- **Marketplace**: `--with-marketplace` combined with `--category`, `--install-policy`, and `--auth-policy` automatically registers the plugin in the manifest.
- **Safety**: `--force` allows non-interactive overwrites during CI/CD automation.

## Frequently Asked Questions

### Where is the argument parsing logic implemented?

The argument parsing logic is implemented in the `parse_args` function of [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py), spanning lines 86 through 148. This function uses Python’s `argparse` library to define positional arguments, optional flags, and their default values.

### What is the default behavior if I only provide a plugin name?

If you only provide the positional `plugin_name` argument, the script creates a minimal plugin directory under `<home>/plugins/<normalized-name>` containing a [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file and a [`README.md`](https://github.com/openai/plugins/blob/main/README.md). No additional subdirectories or Marketplace entries are created unless explicitly requested with flags like `--with-skills` or `--with-marketplace`.

### Can I register a plugin in the Marketplace without creating the directory structure?

No. The `--with-marketplace` flag only updates the manifest to point to `./plugins/<plugin-name>`, but it does not disable the directory creation. To register an existing plugin, you would still run the script with the plugin name and relevant Marketplace flags; use `--force` to skip the "directory already exists" prompt if the plugin folder is already present.

### What are the valid values for the installation and authentication policies?

For `--install-policy`, valid values are `NOT_AVAILABLE`, `AVAILABLE`, and `INSTALLED_BY_DEFAULT` (default: `AVAILABLE`). For `--auth-policy`, valid values are `ON_INSTALL` and `ON_USE` (default: `ON_USE`). These constraints are enforced by the argument parser at lines 132–141 of the source file.