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

The 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 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, 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, 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 file containing MCP server configuration. This option is handled at lines 111–113.

--with-apps

Adds a placeholder .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). 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 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 or 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:

python3 create_basic_plugin.py my-awesome-plugin

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

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

Add placeholder MCP and app definition files:

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

Update the local marketplace manifest with custom metadata:

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:

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 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, 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 file and a 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}