Skip to main content
This guide will help you go from zero to running your first prompt package in minutes.

​
Prerequisites

  • A GitHub or Google account for authentication
  • The Prompts CLI installed on your machine

​
Installation

Install the Prompts CLI using your preferred package manager: 
brew install prompts
Verify the installation: 
prompt --help
1

Authenticate with Prompts.dev

Login using GitHub or Google OAuth:
prompt login
This will open your browser to complete the OAuth flow. By default, GitHub is used as the provider.To use Google instead:
prompt login --provider google
The CLI starts a local server on port 9876 to receive the OAuth callback. You’ll see “Login successful. You can close this tab.” in your browser when complete.
Expected output:
Complete login in your browser...
Logged in successfully
Your JWT token is securely stored in ~/.prompts/config.json.
2

Create your first prompt package

Initialize a new prompt package:
prompt init my-first-prompt
This scaffolds a new prompt package with the following structure:
my-first-prompt/
├── prompt.yaml    # Package metadata and configuration
├── prompt.md      # Your prompt template
└── README.md      # Package documentation
Expected output:
Initialized prompt package in my-first-prompt
Use the --force flag to overwrite existing files if needed.
3

Configure your prompt

Navigate to your prompt directory and edit the prompt.yaml manifest:
cd my-first-prompt
Here’s what the default manifest looks like:
prompt.yaml
name: my-first-prompt
description: Describe your prompt
version: 1.0.0
author: 
inputs:
  - name: product
    required: true
tags:
  - general
Update the manifest with your information:
  • name: Unique identifier for your prompt
  • description: What your prompt does
  • version: Semantic version (e.g., 1.0.0, 1.1.0)
  • author: Your username
  • inputs: Variables your prompt accepts
  • tags: Categories for discoverability
Edit the prompt.md file to define your prompt template:
prompt.md
Write a high-quality product description for {{product}}.

The description should:
- Highlight key features
- Explain benefits to users
- Use clear, engaging language
Use {{variable_name}} syntax to define template variables that match the inputs in your prompt.yaml.
4

Publish your prompt

Publish your prompt to the Prompts.dev registry:
prompt publish
The CLI will:
  1. Load and validate your prompt.yaml manifest
  2. Create a tarball of your prompt package
  3. Upload it to the registry
Expected output:
Published [email protected]
If a prompt with the same name already exists, you’ll receive a conflict error. In that case, you need to increment the version and publish a new version instead.
5

Install and run prompts

Search for available prompts:
prompt search "product description"
Expected output:
NAME                      DESCRIPTION
my-first-prompt          Write product descriptions
other-prompt             Another helpful prompt
Install a prompt package:
prompt install username/my-first-prompt
This installs the latest version to .prompts/my-first-prompt/. To install a specific version:
prompt install username/[email protected]
Expected output:
Installed username/[email protected] into .prompts/my-first-prompt
Run the prompt with variables:
prompt run my-first-prompt --var product="AI chatbot"
Expected output:
Write a high-quality product description for AI chatbot.

The description should:
- Highlight key features
- Explain benefits to users
- Use clear, engaging language
You can pass multiple variables using multiple --var flags:
prompt run my-prompt --var name="value1" --var color="blue"

​
Next steps

Authentication

Learn about OAuth flows and token management

Prompt Packages

Deep dive into prompt package structure

CLI Workflow

Master the complete CLI workflow

API Reference

Explore the REST API endpoints

​
Troubleshooting

​
Login timeout

If login times out after 2 minutes, ensure:
  • Port 9876 is not blocked by a firewall
  • Your browser can reach localhost:9876
  • You completed the OAuth flow in the browser

​
Missing required variables

If you see an error like missing required --var product, ensure all required inputs from prompt.yaml are provided with the --var flag.

​
Unauthenticated errors

If API calls fail with authentication errors:
  1. Verify your token exists: cat ~/.prompts/config.json
  2. Re-authenticate: prompt login
  3. Check the API endpoint: ensure PROMPTS_API_URL environment variable is set correctly (defaults to https://api.prompts.dev/v1)

Build docs developers (and LLMs) love

Get started for freeTalk to us