# Playbooks Docs
> Playbooks is focused on building a new creator economy for developers. Learn more about our platform & SDKs so you can move faster.
## Introduction
# Welcome
This documentation is designed to help you get up and running quickly.
Whether you are looking to grasp the basics, use our CLI, explore the API, or follow our how-to guides, you are in the right place.
---
### Overview
Playbooks is a platform where developers can find inspiration, accelerate their workflow, share knowledge, and monetize their expertise.
It is designed to complement GitHub and the rest of the developer toolchain, not replace them.
In simple terms, Playbooks is a distribution and presentation layer for reusable software with collaboration and organization built in.
---
### How It Works
On Playbooks, a play can represent something small like a component, block, or page; or they can be something more substantial like a starter, template, stack, or full-blown application.
Plays are stateful, must have an interactive / visual element, and must be docker compatible. They must also fit within the confines of our compute limitations.
With Playbooks, developers can:
- browse software plays from other developers
- submit their own software plays for distribution
- collaborate with other developers through comments and private messaging
- organize their library using bookmarks and collections
- take plays with them through the web app, CLI, and agent-friendly workflows
- receive daily transfers through a usage-based revenue share model we call the Ledger
For more on how creator earnings, transfers, and payouts work, see [The Ledger](/concepts/ledger).
---
### Our Mission
We're building a creator economy for developers that blends the best parts of open source with real-world market economics.
We call it hybrid source software.
---
### Market Trends
Software development is changing quickly as AI expands what builders can imagine and create.
At the same time, faster creation leads to more output, more options, and more noise.
That makes trusted starting points, clear product context, and reusable software more valuable, not less.
We believe developers will increasingly want working examples they can evaluate, adapt, and build on with confidence.
Playbooks is built for that shift.
---
### Who It's For
- Developers who want better starting points and faster workflows.
- Designers and product teams who need working inspiration and deployable building blocks.
- Founders who want to accelerate time-to-market with stronger building blocks.
- Creators who want to share what they know and monetize the value they create.
---
# Quickstart
Use this guide to go from a new account to a published play as quickly as possible.
---
### Key Steps
- Create account
- Setup account
- Submit play
- View play
- Share play
- Track performance
- Get paid
---
### Create Account
- Sign up with GitHub to create your Playbooks account.
- Verify your account via the email confirmation.
- Once your account is live, move into the setup wizard.
---
### Setup Account
- Access the setup wizard from your home feed.
- Complete the recommended steps for the best experience and to verify your account.
- Finish merchant setup so your account can receive transfers and payouts.
For a deeper breakdown of account settings, team behavior, and merchant responsibilities, see [Accounts](/concepts/accounts) and [Merchant](/concepts/merchant).
---
### Submit Play
- Paste a GitHub repository URL into the submission field.
- Playbooks will use frontier models to dissect your play, map it into our taxonomy, and prepare it for deployment on our infrastructure.
- Configure the demo until it deploys successfully.
- Complete the final review and publish your play.
For more on deployment strategies, environment variables, private files, and debugging, see [Demos](/concepts/demos).
---
### View Play
- Open your play from your profile after it is published.
- Familiarize yourself with the play experience and the actions available to you, including bookmarks, cloning, downloading, and sharing.
- This is also a good time to download the CLI and get familiar with that interface through [CLI Quick Start](/cli/quickstart).
- Use the visibility settings to control whether it appears in the marketplace or stays available by direct URL only.
---
### Share Play
- Familiarize yourself with the built-in sharing tools by sending your play to yourself or another user.
- Use marketplace visibility or a direct private URL depending on how widely you want to distribute it.
- Use `@playbooks/widgets` to embed your play directly on your own website.
---
### Track Performance
- Follow verified play activity through [The Ledger](/concepts/ledger).
- Use the public and private ledger views to monitor performance and earnings.
- Expect the ledger to process activity on a daily cycle with a rolling verification lag.
---
### Get Paid
- Keep your merchant and account in good standing. For setup details, see [Merchant](/concepts/merchant).
- Playbooks will automatically aggregate ledger activity into a single transfer on a daily basis.
- Manage payout settings and merchant activity from your account dashboard.
For more on the revenue share model and the 60/40 split, see [The Ledger](/concepts/ledger).
---
# Infrastructure
This page covers the basics behind the Playbooks infrastructure and why it sits at the core of the product.
It is what allows us to host a wide range of projects in a secure, meaningful, and affordable way.
---
### Overview
At Playbooks, we built a proprietary runtime that can host anything from a small primitive like a component to a more complex project like a stateful application.
#### Key Tenets
- on demand execution
- serverless runtime behavior
- secure, sandboxed environments
- shared infrastructure with load-balanced demo traffic
- ephemeral execution with caching after successful boots
---
### How It Works
- We fetch the source code from GitHub or another connected project source.
- We prepare it for deployment using either your configuration or AI-generated defaults.
- We boot the play inside an isolated runtime environment.
- If the demo runs, the environment is cached and made available for future boots.
- If the demo fails, the play is temporarily removed from the marketplace until it is fixed.
---
### Your Sandbox
Each play is allocated it's own sandbox that's optimized for fast, clean boots where execution state is never written to persistent disk.
- Plays run inside a base environment optimized for Playbooks.
- Plays run using Docker-compatible configuration.
- Each sandbox is isolated and secure.
- Sandboxes are given hard limits on compute, memory, and disk.
- The runtime is ephemeral by design.
At a high level, this gives developers a reliable place to present working software on-demand without needing to manage the hosting layer themselves.
---
### Resources
Resources are limited at the moment and subject to change.
- `2` vCPUs
- `4GB` memory
- `4GB` disk
- `1GB` shared memory
---
### Debugging
- built-in logs
- browser-based shell access
- runtime stats and operational visibility
- tools that help you understand whether a demo is healthy and behaving as expected
For a deeper dive, see [Demos](/concepts/demos).
---
### Environment Variables
- account-level environment variables can be shared across projects
- project-level environment variables can override account defaults
- variables are injected at runtime rather than shipped with the downloadable source
---
### Private Files
- account-level private files can be reused across projects
- project-level private files can override account defaults
- private files are mounted at runtime and stripped from the distributed code
Collectively, this infrastructure is what allows Playbooks to present software as something live, testable, and ready to evaluate rather than just another repository link.
---
# Artificial Intelligence
Playbooks uses AI to accelerate publishing, deployment, and developer workflows without compromising ownership, intellectual property, or control.
---
### How Playbooks Uses AI
- Playbooks uses frontier models to dissect your play, map it into our taxonomy, and prepare it for deployment on our infrastructure.
- That turns raw repositories into structured, discoverable, and demo-ready plays with less manual setup.
For more on the publishing flow, see [Quickstart](/intro/quickstart) and [Demos](/concepts/demos).
---
### AI Across The Platform
- For the definitive LLM version of these docs, fetch `https://www.playbooks.xyz/docs/llms.txt` directly.
```sh filename="Terminal" copy
curl -L https://www.playbooks.xyz/docs/llms.txt
```
- For a single page, use the same docs path plus `.md`, or use **Copy Markdown** / **View Markdown** in the docs UI.
```sh filename="Terminal" copy
curl -L https://www.playbooks.xyz/docs/cli/overview.md
```
- Use `@playbooks/mcp` for agent workflows and `@playbooks/cli` for terminal workflows.
Learn more in [MCP Overview](/mcp/overview) and [CLI Overview](/cli/overview).
---
### Developer First
- We use AI to reduce friction across discovery, distribution, deployment, and workflow acceleration.
- The goal is to help developers move faster while protecting the value and integrity of their work.
---
---
# Overview
The `playbooks.json` configuration file lets you specify various Play properties via code for faster deployments and precise details.
---
### How it Works
Simply include a `playbooks.json` file at the root of your project and our system will automatically read and apply it when connecting or syncing your play.
If for some reason, you encouter issues, make sure and check your console logs as each segment may break if you have the wrong configuration and / or properties.
---
### The Configuration File
```json filename="Playbooks.json" copy
{
"coverType": "",
"cover": "",
"video": "",
"poster": "",
"thumbnail": "",
"name": "",
"description": "",
"variant": "",
"setup": {
"welcomeComplete": true,
"basicsComplete": true,
"connectionComplete": true,
"mediaComplete": true,
"techComplete": true,
"demoComplete": true,
"reviewComplete": true
},
"qualities": {
"hasDemo": true,
"hasReadme": true,
"hasLicense": true,
"hasDistribution": true
},
"demo": {
"strategy": "",
"subdomain": "",
"port": 3000,
"subdirectory": "",
"dockerfile": "",
"dockercompose": "",
"image": "",
"template": "",
"networks": [],
"env": [],
"files": [],
"commands": [],
"https": true
},
"frameworks": [],
"languages": [],
"platforms": [],
"packages": [],
"tools": [],
"tags": []
}
```
---
# Community Guidelines
Playbooks is a platform for creativity and knowledge sharing.
These guidelines help keep the platform useful, respectful, and trustworthy.
---
### Our Standard
We're committed to building a premium, curated, and safe ecosystem for developers at all skill levels.
Published plays should be useful, presentable, deployable, and respectful of the broader developer community.
---
### Publishing
If you publish on Playbooks, you are responsible for the code, assets, and claims attached to your play.
- You must have the legal right to share, distribute, and monetize the code you publish.
- Your play should be clearly presented and understandable to other developers.
- Your play must follow our product requirements and community standards.
- If we identify a policy, quality, or deployment issue, you are expected to address it promptly.
For the deeper product requirements, see [Plays](/concepts/plays) and [Demos](/concepts/demos).
---
### Deployment
Deployment is a core part of the Playbooks experience.
We require internal hosting because working software is more useful than a static listing.
- All published plays must deploy on Playbooks infrastructure.
- All plays should include an interactive or visual way for others to evaluate the project.
- When syncing a play, we automatically re-deploy it.
- If a synced update breaks deployment, it's automatically removed from the marketplace until it is fixed.
- Broken or unpublished plays can be managed through the web application.
---
### Merchant / Account
- Your account must be in good standing to publish a play.
- Your account and merchant must be in good standing to receive transfers.
- Your account and merchant must be in good standing to receive payouts.
For more, see [Accounts](/concepts/accounts) and [The Ledger](/concepts/ledger).
---
### Community Conduct
We expect participants to act in good faith and contribute to a healthy ecosystem.
- Do not publish harmful, abusive, fraudulent, deceptive, or infringing content.
- Do not use comments, messages, or profiles to harass, impersonate, or spam others.
- Do not misrepresent what a play does, how it is licensed, or what users will receive.
- Respect the broader community and the collaborative spirit of the platform.
---
### Consumer Responsibility
Playbooks gives developers better tools to evaluate software, but you are still responsible for the code you take with you.
- Review code, dependencies, licenses, and production-readiness before shipping.
- Use your own judgment when adopting third-party software.
- Treat downloaded code as something to evaluate carefully, not blindly trust.
---
### Reporting and Moderation
We rely on the community to help identify both high-quality work and content that should not be on the platform.
- If something appears offensive, harmful, fraudulent, or out of place, please report it.
- Use the built-in reporting tools where available so our team receives the right context.
- We reserve the right to remove content, restrict accounts, or take other moderation actions when necessary.
---
### These Will Evolve
Playbooks is still growing, and these guidelines will evolve as the product and community mature.
---
# Comparisons
While Playbooks shares features with other developer platforms and emerging tools, our core mission is building a creator economy for developers.
IN nearly every instance, Playbooks complements the following categories as a platform for discovery, distribution, social interaction / collaboration and monetization.
---
### Key Differentiators
- **Robust Discovery:** Find, filter, and adopt the exact code you want.
- **Unlimited Sharing:** Publish unlimited plays with free cloud hosting.
- **Active Collaboration:** Engage with your peers through follows, comments, and messages.
- **Seamless Organization:** Curate your workflow using bookmarks and collections.
- **Portability:** Leverage `@playbooks/cli` for easy add, download, and clone capabilities.
- **Universal Access:** Embed your work seamlessly on any website using `@playbooks/widgets`.
- **Revenue Share:** Earn daily payouts based on the tangible value your code brings to the network.
- **Platform Agnostic:** We are designed to complement, not replace, the tools you already love.
---
### AI: General Purpose Agents
These platforms excel at small coding tasks, brainstorming, and strategy.
They are incredible tools for streamlining the creation process and generating functional code snippets.
However, developers often still rely on manual clipboard workflows to move and implement that code.
**Notable Platforms:**
- ChatGPT
- Claude
- Gemini
---
### AI: Coding Agents
These tools are designed to assist developers directly within the IDEs and environments where they already work.
They integrate smoothly into your existing codebase, read from pre-written context files, and manipulate code directly.
They are incredibly powerful companions for the actual writing and refactoring of software.
**Notable Platforms:**
- Claude Code
- GitHub Copilot
- OpenAI Codex
---
### AI: Vibe Coding Platforms
These platforms focus on helping developers rapidly build applications within highly optimized, opinionated frameworks.
For example, tools like v0 are fantastic for generating UIs tailored specifically for Next.js and Vercel infrastructure.
They provide incredibly fast prototyping and streamline the initial build phase.
Playbooks aims to partner with these workflows by offering a framework-agnostic layer for discovery, allowing you to share and monetize those platform-specific creations across the broader developer ecosystem.
**Notable Platforms:**
- v0
- Bolt.new
- Lovable
---
### Code Storage & Collaboration
These platforms serve as the essential backbone of modern software development.
At their core, they excel at code storage, version control, and team collaboration.
Playbooks is intentionally designed to sit directly on top of this foundational infrastructure.
By integrating deeply with these tools, we pull your existing repositories into a seamless marketplace, adding discovery and monetization layers without disrupting your core version control workflows.
**Notable Platforms:**
- GitHub
- GitLab
- Bitbucket
## Concepts
# Accounts
An account is the core identity model in Playbooks.
It gives each developer their own settings, data, and activity while also allowing them to create or join teams when they need to collaborate under a shared entity.
---
## How It Works
- Every user has an individual account.
- That account is responsible for its own profile, settings, preferences, and activity.
- At the same time, a user can create or join one or more teams.
- You can then switch between your personal account and any team account you belong to, depending on who you want to act as.
---
## Individual and Team Context
Your individual account is where your personal activity begins.
It is used to discover plays, save content, submit work, and manage your own experience on the platform.
Teams extend that model into a shared context.
When you switch into a team, you are acting on behalf of that organization rather than yourself.
For more on seats, roles, and shared ownership, see [Teams](/concepts/teams).
---
## Related Settings
Accounts are closely connected to other parts of the platform, including billing, merchant setup, and collaboration.
Those concepts are documented separately so each page can stay focused.
- For payout and verification details, see [Merchant](/concepts/merchant).
- For collaborative account behavior, see [Teams](/concepts/teams).
---
# Merchant
A merchant is the payout profile Playbooks creates on your behalf through Stripe.
It allows the platform to verify your identity, collect the required payout details, and distribute earnings from the Ledger to your bank account.
---
## What It Does
- Creates and manages a connected merchant account through Stripe.
- Handles the KYC and identity-verification requirements needed to participate in revenue share.
- Collects your banking information through Stripe so payouts can be delivered safely.
- Receives the transfers that Playbooks generates from verified Ledger activity.
---
## Where to Manage It
You can view and manage your merchant details at any time from `Playbooks > Settings > Merchant`.
This is where you complete setup, review your verification status, and keep your payout information up to date.
For more on how verified activity turns into transfers and payouts, see [The Ledger](/concepts/ledger).
---
## Requirements
- We defer to Stripe for the core KYC and eligibility requirements tied to your merchant account.
- Please familiarize yourself with Stripe's age limits and country restrictions before starting setup.
- Beyond that, Playbooks monitors the platform closely to ensure safe, well-intentioned behavior.
---
## Good Standing
Your merchant must remain in good standing to receive transfers and payouts.
Playbooks may pause or disable merchant access for incomplete verification or for inappropriate, harmful, or illicit behavior on the platform.
---
# Plays
Plays are the core unit of distribution on Playbooks.
They can range from a small primitive like a component to a complex, multi-service application.
---
## How It Works
Every play is connected directly to a GitHub repository or a subdirectory within one.
When you submit a play, we automatically fetch, format, categorize, and store the code on our servers.
We then prepare the code for deployment within a secure, isolated sandbox.
As the owner, you retain full control and can edit any detail of your play at any time.
---
## Requirements
To keep the experience premium and reliable, plays must meet a few core criteria.
- **Visual:** Every play should include a cover image or an interactive video demo.
- **File Size:** The total file size for your play must remain under 100MB.
- **Deployment:** Your play must successfully deploy and run on our cloud infrastructure.
- **Respectful:** All plays should be respectful of the broader community and are subject to takedown requests.
- **Distribution:** You must have the legal right to share, monetize, and distribute the code you are publishing.
---
## Variants
When adding a play, you'll need to select an appropriate variant.
This allows us to properly categorize your project and accurately track the credits required per download.
| Variant | Credits | Purpose |
| :------------ | :-----: | :-------------------------------------------------------------------------------- |
| **Starters** | 1 | Basic, unopinionated building blocks needed to launch a new project. |
| **Partials** | 3 | Specific, modular functionality designed to be dropped into an existing project. |
| **Templates** | 5 | Advanced, pre-configured building blocks tailored for specific use cases. |
| **Stacks** | 10 | Layered, stateful solutions that often encompass multiple services or containers. |
| **Apps** | 20 | Comprehensive, plug-and-play solutions that are nearly ready for production. |
---
## Connections
Plays should maintain a connection to a host GitHub repository or subdirectory at all times.
Syncing your play will automatically pull in the latest commits and changes from the host repository.
If a sync breaks deployment, the play is temporarily removed from the marketplace until it is successfully re-deployed.
---
## Demos
Every play is provisioned with a live demo on Playbooks infrastructure so users can evaluate working software rather than a static listing.
A functional, running demo is required to publish your play to the public marketplace.
For more on configuration, debugging, and runtime behavior, see [Demos](/concepts/demos).
---
## Code Explorer
Each play features a built-in code explorer that provides a familiar, intuitive viewing experience similar to the GitHub UI.
Before committing credits, users can freely preview the project's high-level file tree and read the accompanying documentation.
To view the actual source code within the explorer, users must unlock the play, which deducts credits as a download.
Once a play is downloaded, the user enjoys unlimited, lifetime access to explore and utilize the underlying code.
---
## Downloads
Each play includes a variety of built-in tools to easily download, clone, or add the underlying code directly to an existing project.
Download activity also serves as a key input in how usage and creator earnings are tracked across the platform.
For delivery options and access methods, see [Downloads](/concepts/downloads).
---
## Visibility
Plays can be explicitly toggled as either public or private.
Private plays are hidden from the marketplace and are only accessible to the outside world via a direct, shareable URL.
However, as the owner, you will always be able to view and manage all of your plays directly from your private profile.
---
# Library
The Library is your personal organization layer inside Playbooks.
It gives bookmarks and collections a first-class home so you can save useful plays, group them by project or client, and get back to them quickly.
---
## What It Does
- Gives you a dedicated place to organize your Playbooks activity.
- Helps you save individual plays with bookmarks.
- Lets you group related items into collections for a project, workflow, or use case.
- Makes it easier to return to the code, creators, and ideas you want to keep close.
---
## How To Use It
Use bookmarks when you want to save something quickly.
Use collections when you want to curate a set of plays around a specific goal, client, or area of interest.
The Library is meant to feel lightweight and practical, whether you are gathering inspiration, building a shortlist, or organizing work for later.
---
# Downloads
Downloads are how code leaves Playbooks and enters your workflow.
They are one of the most important parts of the platform because they turn discovery into actual usage.
---
## How It Works
- Find a play and choose how you want to take delivery.
- Playbooks prepares the source and records the download event.
- The required credits are deducted from your balance or applied to metered usage.
- From there, the code moves into your local workflow through the method you selected.
---
## Delivery Options
- **Add:** Places the code in the appropriate location and runs install commands when supported.
- **Download:** Delivers the source so you can place and manage it yourself.
---
## Access Methods
- Browser download
- API request
- GitHub clone flow
- `playbooks/cli` which contains full-suite of account management, search, discovery, and download tools
- `playbooks/mcp` which provides a comprehensive wrapper around the `@playbooks/cli` for agents
---
# Demos
A demo is the live, hosted version of a play running on Playbooks infrastructure.
It lets users evaluate software in a working state instead of relying on screenshots or the code explorer alone.
---
## How It Works
- When you submit a play, Playbooks will attempt to generate a working configuration.
- As an alternative, you can define your own configuration using [`playbooks.json`](/intro/playbooks-json).
- The project is then booted inside an isolated sandbox on our infrastructure.
- If the demo deploys successfully, the play can be published and served to visitors.
- If the demo fails, it must be fixed before the play can remain available.
---
## Configuration
Demos are primarily configured during the submission process, where you can manage each part of the setup through the user interface.
The following sections outline the primary parts of that configuration.
### Strategies
| Strategy | Description |
| :------------- | :---------------------------------------------------------------------------------- |
| **Basic** | Provide the base image, port, and server commands so Playbooks can build the setup. |
| **Dockerfile** | Supply your own Dockerfile when you want full control over the container. |
| **Compose** | Use Docker Compose when your demo depends on multiple services working together. |
| **Partial** | Build from an existing template and define where the runtime code should live. |
### Environment Variables
Environment variables are useful when your demo needs secrets or runtime configuration that should not be bundled with the distributed source code.
They are injected at runtime and can be managed without changing the underlying repository.
| Key | Value |
| :------------- | :--------------------------------- |
| `PORT` | `••••••••••••••••••••••••••••••••` |
| `NODE_ENV` | `••••••••••••••••••••••••••••••••` |
| `DATABASE_URL` | `••••••••••••••••••••••••••••••••` |
### Private Files
Private files solve a similar problem when your demo depends on runtime-only files such as configuration files, certificates, or package credentials.
Like environment variables, they are mounted at runtime and excluded from the code users receive when they download a play.
| Path | Value |
| :-------- | :--------------------------------- |
| `/.env` | `••••••••••••••••••••••••••••••••` |
| `/.npmrc` | `••••••••••••••••••••••••••••••••` |
---
### Optimizations
A few small decisions can make a big difference in demo performance and boot speed.
- Use smaller base images when possible so builds and startups stay faster.
- Build for production rather than development so the resulting output is leaner and closer to what users should evaluate.
- Move as much work as possible into the build process instead of doing it at runtime.
- Keep the run command focused on basic serve behavior so cold starts remain as fast as possible.
---
## Debugging
All demos include built-in debugging tools so you can understand how a deployment is behaving after boot.
These tools can be viewed at the sandbox level or narrowed to individual services when a demo runs more than one process.
| Tool | Purpose |
| :---------- | :-------------------------------------------------------------------------------------- |
| **Info** | View the live Docker configuration for the sandbox and its services. |
| **Logging** | Inspect real-time output during boot and runtime. |
| **Shell** | Open a browser-based shell for direct inspection and debugging. |
| **Stats** | Monitor resource usage and runtime behavior while the demo is live. |
Use these tools to verify startup commands, inspect service behavior, and troubleshoot failed or unstable deployments.
For a broader look at sandbox behavior, compute limits, and runtime infrastructure, see [Infrastructure](/intro/infrastructure).
---
# Widgets
Widgets are the lightweight embed layer for Playbooks.
They let you place plays on your own website, documentation, or README so people can discover your work outside the core app.
---
## What They Do
- Embed plays outside of Playbooks.
- Extend distribution to docs, landing pages, portfolios, and developer websites.
- Keep the sharing experience lightweight and portable.
---
## Getting Started
Configure widgets through the [widgets app](https://playbooks.xyz/widgets), then install the package:
```shell
npm install @playbooks/widgets
```
---
# Chats
Chats give developers a private way to communicate directly inside Playbooks.
It is built for lightweight collaboration around plays, profiles, and shared work.
---
## What It Does
- Supports direct messages and group conversations.
- Lets you create sub-threads inside a chat.
- Allows attachments such as plays, frameworks, and user profiles.
- Keeps communication close to the work instead of pushing it into another tool.
---
## Access
All users can receive and participate in existing chats.
However, only Pro subscribers and above can initiate a chat.
It is designed to help individuals and teams coordinate around discovery, publishing, and support without leaving the platform.
---
## Privacy and Controls
- Block or report another user at any time.
- Mute chats you do not want to follow closely.
- Edit chats and manage threads as conversations evolve.
- Edit individual messages as needed.
---
# Taxonomy
The Playbooks taxonomy is our core engine for discovery. It makes the platform easy to navigate, customizable, and personal for every developer.
---
## How it Works
To improve discovery, we break down our taxonomy into several searchable categories.
| Category | Type | Description |
| :------------- | :----- | :------------------------------------------------------------------------- |
| **Frameworks** | Basic | Established development structures like Next.js or Express. |
| **Languages** | Basic | Core primitives like TypeScript, Go, or Rust. |
| **Packages** | Basic | Dependencies identified directly from your configuration files. |
| **Platforms** | Basic | The area of the stack the play satisfies (e.g., Frontend, Auth, Database). |
| **Tools** | Basic | Essential developer utilities like Docker or Turborepo. |
| **Tags** | Basic | Community-driven labels for specific use cases or features. |
| **Users** | Entity | Individual developers sharing and monetizing their expertise. |
| **Teams** | Entity | Collaborative groups distributing plays as a single organization. |
---
## Why This Matters
A robust taxonomy transforms the marketplace from a static list into a dynamic ecosystem.
- **Global Search:** Every aspect of the taxonomy is indexed and searchable.
- **Contextual Discovery:** Navigating a specific tag or framework surfaces all related high-quality plays.
- **Personalized Feeds:** You can follow specific languages or tools to curate a unique dashboard.
- **Smart Recommendations:** We use your taxonomy preferences to suggest plays that fit your specific stack.
---
# Subscriptions
Playbooks offers flexible subscription plans for individual developers, growing teams, and enterprise customers.
The model is designed to scale with usage while keeping discovery, publishing, and collaboration accessible.
---
## Philosophy
Subscriptions are meant to keep Playbooks simple to use and aligned with actual usage.
Instead of paying item by item, you get access and credits that scale with how you work.
---
## Subscription Tiers
We offer three primary products tailored to different stages of the developer journey.
| Feature | Free | Pro | Enterprise |
| :-------------------------- | :--: | :---------: | :--------: |
| **Monthly Credits** | 10 | 50 - 1,000+ | Custom |
| **Unlimited Publishing** | ✅ | ✅ | ✅ |
| **Sandbox Resources** | ✅ | ✅ | ✅ |
| **Credit Rollover** | ❌ | ✅ | ✅ |
| **Direct Messaging** | ❌ | ✅ | ✅ |
| **Private Instances** | ❌ | ❌ | ✅ |
| **SSO & Dedicated Support** | ❌ | ❌ | ✅ |
---
## Pro Pricing
The Pro tier is designed to grow with you.
Each plan includes a monthly credit allotment, after which a metered discount applies for additional usage.
| Plan Level | Monthly Price | Annual Price (Total) | Included Credits | Metered Rate |
| :---------- | :-----------: | :------------------: | :--------------: | :------------: |
| **Starter** | $25 / mo | $240 / yr | 50 | $0.50 / credit |
| **Basic** | $50 / mo | $480 / yr | 150 | $0.33 / credit |
| **Plus** | $100 / mo | $960 / yr | 400 | $0.25 / credit |
| **Growth** | $200 / mo | $1,920 / yr | 1,000 | $0.20 / credit |
---
## Student Discounts
Students with a valid student email address are eligible for a 50% discount on any paid subscription tier.
---
## Volume Discounts
Volume discounts are available for larger teams.
If you are rolling Playbooks out across a bigger organization, we are happy to work with you on a structure that better fits your team size and usage pattern.
---
## Enterprise Offering
Our Enterprise service is designed for customers who need more control, isolation, and a tailored rollout.
It is a white-labeled infrastructure offering with support for:
- dedicated instances
- private networking
- custom compute
- SSO
- white-glove onboarding
- dedicated support
If you are evaluating Playbooks for a larger organization or a more custom deployment model, please reach out through the pricing page to start the conversation.
---
## Plan Changes
Because subscriptions are closely tied to seats and usage, plan changes take effect immediately.
This is partly to avoid gamification but also to keep things simple.
---
# Teams
Playbooks supports the concept of team accounts, allowing groups of individual users to share access to the marketplace and distribute plays as a single entity.
---
## Philosophy
Teams allow a group of users to discover, share, and collaborate across the platform as a unified organization.
This is particularly effective for managing high volumes of community engagement, such as comments and private messages.
Furthermore, teams allow you to distribute code and earn revenue into a shared balance.
Each team is responsible for managing its own merchant account, subscription tier, and billing details independently of its members' personal accounts.
---
## Settings
Teams include specific management features designed to scale your collaborative workflow.
#### Seats
Because teams share resources and revenue, you must upgrade to a paid subscription and provision seats before inviting members.
For example, if you intend to invite five users to your team, you must first purchase five seats within your billing dashboard.
---
#### Members
Once seats are available, the team owner can invite users to join the organization.
During the invitation process, you can define specific roles to control access levels and permissions.
The team owner can update roles or remove members at any time.
Removing a member immediately frees up that seat, allowing you to invite a new collaborator without additional billing changes.
| Role | Permissions |
| :--------- | :---------------------------------------------------------------- |
| **Owner** | Full access to billing, merchant settings, and member management. |
| **Admin** | Can manage plays, respond to messages, and invite new members. |
| **Member** | Can create and edit plays and participate in team discussions. |
---
# Usage
Playbooks uses a usage-based credit system to unlock and download marketplace content.
## How it Works
Credits are allocated on a monthly basis based on your subscription.
- **Subscriptions:** Every paid tier includes a monthly credit allotment.
- **Metered Discounts:** High-volume usage beyond your allotment is available at a discount.
- **Credit Rollover:** For Pro accounts, unused credits will rollover to the next month.
- **Free Exploration:** Browsing profiles, interacting with demos, and community engagement cost nothing.
- **Unlocking Value:** Credits are only consumed when you unlock the full source code or download a play.
| Activity | Credit Cost |
| :----------------- | :---------: |
| Demos | 0 |
| Code Preview | 0 |
| Full Code Access | Variable |
| Downloads | Variable |
---
## Tracking
- **Quick View:** Check your balance via the `` at the bottom left.
- **Usage Ledger:** Access a detailed breakdown of your credit consumption in account settings.
---
# The Ledger
The Ledger is the economic engine of Playbooks, providing a transparent system for tracking performance and distributing revenue.
It utilizes a dual-ledger approach to balance platform transparency with creator privacy.
- **Public Ledger:** Displays account-level performance and network activity using private hash keys to anonymize individual identities.
- **Private Ledger:** Provides creators with a granular, play-level view of their specific performance and earnings.
---
## Philosophy
The Ledger is treated as an immutable source of truth.
By providing a clear, audit-ready trail of activity, we ensure that every creator is rewarded fairly for the value they contribute to the network.
## How it Works
The economic engine follows a structured, daily cycle to calculate and record network activity.
- **Daily Execution:** The Ledger runs every 24 hours with a rolling 30-day verification lag to ensure all transactions are finalized.
- **Account Validation:** The system only processes data for accounts and teams currently in good standing.
- **Activity Computation:** We aggregate "Unique Downloads"—the total credits consumed by users unlocking your plays for the first time.
- **Immutable Recording:** The total activity for the network and the specific performance of each play are stashed in the ledger as a permanent record.
- **Revenue Share:** Finally, we split revenue with a 60/40 breakdown favoring creators over the platform.
---
## Transfers
Once the daily Ledger concludes, the system initiates individual transfers.
- **Granular Tracking:** A separate transfer is generated for every play that earned credits, allowing you to see exactly which projects are driving your revenue.
- **Merchant Verification:** Transfers are only dispatched to accounts that have successfully completed the merchant setup wizard.
- **Ledger Stashing:** These transfers act as the bridge between your play's performance and your overall merchant balance.
---
## Payout Pipeline
The final stage of the economic cycle is the aggregation of funds into your account.
- **Automated Aggregation:** Playbooks automatically groups all open, verified transfers for your account into a single payout batch.
- **Processing:** Payouts are processed daily, ensuring a consistent flow of liquidity to creators.
- **Flexible Control:** While automated payouts are the default, you can toggle this behavior off in your settings to manually request withdrawals at your convenience.
- **Notifications:** You will receive a real-time notification whenever a transfer is recorded or a payout is successfully initiated.
---
# Referrals
The referral system gives every account the opportunity to earn discounts by sharing Playbooks with their network.
Our growth is driven by the community, and we believe in rewarding users who help expand the ecosystem.
---
## "Give $20, Get $20"
We offer a straightforward incentive for both the advocate and the new user.
When someone signs up for a paid plan using your unique referral code, both parties benefit.
| Action | Reward | Condition |
| :------- | :--------------- | :--------------------------------------------------------- |
| **Give** | **$20 Discount** | Friend signs up using your link or code. |
| **Get** | **$20 Credit** | Applied to your invoice after they upgrade to a paid plan. |
---
## How it Works
The process is designed to be seamless for both the referrer and the guest.
- **Locate Your Link:** Navigate to **Account > Settings > Referrals** to find your unique referral URL and code.
- **Share Your Network:** Copy and share your link via social media, email, or your own developer blog.
- **Guest Onboarding:** When a guest arrives via your link, they will be prompted to sign up with your code pre-applied.
- **Manual Registration:** If a user is already on the platform but hasn't upgraded, they can manually register your code in their settings.
- **Activation:** We track the referred user until they upgrade to any of our Pro subscription tiers.
- **Reward Distribution:** Once their first paid invoice is processed, a $20 discount is automatically applied to your account.
---
## Program Rules
To make the referral system as rewarding as possible, we have established the following guidelines:
- **Stackable Discounts:** There is no limit to how many rewards you can earn.
If multiple referrals upgrade in the same month, those discounts will stack and apply toward your total invoice amount.
- **No Expiration:** Referral rewards do not expire.
If your earned discounts exceed your current invoice total, the remaining balance will carry over to your next billing cycle.
- **Unlimited Referrals:** You can share your code with as many people as you like.
There is no cap on the number of successful referrals an account can generate.
---
## Status Tracking
You can monitor the success of your referrals in real-time within your account dashboard.
[Image of a referral tracking dashboard showing pending, successful, and total rewards earned]
- **Pending:** Users who have signed up with your code but have not yet upgraded to a paid plan.
- **Successful:** Referrals that have completed an upgrade and triggered a reward.
- **Total Earned:** A lifetime summary of money earned
## CLI
# Overview
Download the Playbooks CLI to access your [Playbooks](https://www.playbooks.xyz) account and perform basic tasks directly from your terminal or a remote server.
---
## Prerequisites
- Node
- Playbooks
---
## Description
The Playbooks CLI gives developers quick & easy terminal access to their Playbooks account so they can browse, inspect, download, clone, and manage plays from anywhere.
Using the CLI, developers can also toggle in and out of their associated accounts making it a breeze to perform similar actions on behalf of those entities.
After installation, you can use the `playbooks` command to run commands against our servers via your terminal.
---
# Quick Start
Use this page to get the Playbooks CLI installed, connected, and ready for day-to-day use.
---
## 1. Install the CLI
```sh filename="Terminal" copy
npm install -g @playbooks/cli
```
Install the CLI on your local machine or any remote environment where you want terminal access to Playbooks.
---
## 2. Check connectivity
```sh filename="Terminal" copy
playbooks ping
```
A successful response confirms the CLI is installed and can reach the Playbooks API.
---
## 3. Login
For most developers, the guided login flow is the simplest place to start.
```sh filename="Terminal" copy
playbooks login
```
If you already have credentials and want a non-interactive flow, you can pass them directly.
```sh filename="Terminal" copy
playbooks login --email steve@apple.com --password ********
```
---
## 4. Run your first commands
Once authenticated, these are a few good first commands:
```sh filename="Terminal" copy
playbooks account
playbooks config
playbooks plays --query next
```
Use `playbooks account` to confirm the active account, `playbooks config` to inspect the active config, and `playbooks plays` to start browsing marketplace content.
---
For the full command tree, continue to [Commands](/cli/commands) and [Examples](/cli/examples).
---
# Configuration
The Playbooks CLI will look for a config file at the following location `~/.playbooksrc` containing your platform secrets. If one does not exist, the Playbooks CLI will create one for you when you login.
As an alternative, you can provide a custom config file location using the `--config` flag as part of any command.
---
## Sample config
Here is a sample config file located at the default location on your file system.
```bash
id=1
name=Eric Hubbell
uuid=eric-hubbell
email=eric@playbooks.xyz
token=********
...
```
---
# Global Options
The Playbooks CLI comes with a series of global options that can be appended to the global or an individual command.
---
## Usage
Here are a couple of common usage patterns:
```sh
playbooks --help
playbooks --version
playbooks login --help
playbooks login --config ~/path/to/.playbooksrc
playbooks download --help
playbooks download --config ~/path/to/.playbooksrc
```
---
## Types
The Playbooks CLI expects the following types for each option:
| Option | Type | Description |
| --------- | ------- | ------------------------------------------------ |
| --config | string | Path to a custom playbooks config file location. |
| --help | boolean | Display help menu for an individual command. |
| --version | boolean | Display the current package version. |
---
# Commands
CLI reference with copyable examples and supported options.
All commands also support the `--config` flag. See [Global Options](/cli/global) for shared flags.
---
## Account
Display which account is currently active.
Use `playbooks account ` for account-scoped resources.
```sh filename="Terminal" copy
playbooks account
playbooks account --select 'id,name,email'
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of account fields you'd like to display |
#### Banks
View your account banks.
```sh filename="Terminal" copy
playbooks account banks
playbooks account banks --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Bookmarks
View your account bookmarks.
```sh filename="Terminal" copy
playbooks account bookmarks
playbooks account bookmarks --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Cards
View your account cards.
```sh filename="Terminal" copy
playbooks account cards
playbooks account cards --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Charges
View your account charges.
```sh filename="Terminal" copy
playbooks account charges
playbooks account charges --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Collections
View your account collections.
```sh filename="Terminal" copy
playbooks account collections
playbooks account collections --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Drafts
View your account drafts.
```sh filename="Terminal" copy
playbooks account drafts
playbooks account drafts --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Downloads
View your account downloads.
```sh filename="Terminal" copy
playbooks account downloads
playbooks account downloads --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Invoices
View your account invoices.
```sh filename="Terminal" copy
playbooks account invoices
playbooks account invoices --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Ledgers
View your account ledger activity.
```sh filename="Terminal" copy
playbooks account ledgers
playbooks account ledgers --select 'id,amount,type'
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
#### Payouts
View your account payouts.
```sh filename="Terminal" copy
playbooks account payouts
playbooks account payouts --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Plays
View your account plays.
```sh filename="Terminal" copy
playbooks account plays
playbooks account plays --status draft --page 1
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--status` | `string` | Filter by status |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Subscription
Fetch and display your account subscription.
```sh filename="Terminal" copy
playbooks account subscription
playbooks account subscription --select 'id,name,uuid,email'
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
#### Teams
View a list of your account teams.
```sh filename="Terminal" copy
playbooks account teams
playbooks account teams --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
This command is only available when a user account is active.
#### Transfers
View your account transfers.
```sh filename="Terminal" copy
playbooks account transfers
playbooks account transfers --page 2 --pageSize 25
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
#### Usage
Fetch and display your account usage statistics.
```sh filename="Terminal" copy
playbooks account usage
playbooks account usage --select 'id,totalCredits,totalRemaining'
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
## Add
Add a play to your local project and run install commands.
```sh filename="Terminal" copy
playbooks add
playbooks add --path ~/path/to/folder
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--path` | `string` | Path to a custom destination folder |
| `--name` | `string` | Custom name for the directory |
| `--version` | `string` | Specify a specific version to add |
## Clone
Clone a play to your GitHub account.
```sh filename="Terminal" copy
playbooks clone
playbooks clone --account mile-hi-labs --private
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--account` | `string` | Clone to a specific account |
| `--name` | `string` | Rename the cloned play |
| `--private` | `boolean` | Mark the cloned play as private |
| `--version` | `string` | Specify the version ID |
## Collections
Fetch collection related resources.
```sh filename="Terminal" copy
playbooks collections
playbooks collections --query next
playbooks collections starter-packs
playbooks collections starter-packs open
playbooks collections starter-packs --include team
playbooks collections starter-packs plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Config
Display your config file.
```sh filename="Terminal" copy
playbooks config
playbooks config --select 'token,uuid'
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
## Download
Download a play to your local machine.
```sh filename="Terminal" copy
playbooks download
playbooks download --path ~/path/to/folder
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--path` | `string` | Path to a custom destination folder |
| `--name` | `string` | Custom name for the directory |
| `--version` | `string` | Specify a specific version to download |
## Frameworks
Fetch framework related resources.
```sh filename="Terminal" copy
playbooks frameworks
playbooks frameworks --query next
playbooks frameworks react
playbooks frameworks react open
playbooks frameworks react --include team
playbooks frameworks react plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Init
Add a `playbooks.json` file to your project.
```sh filename="Terminal" copy
playbooks init
playbooks init --path ~/path/to/project
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--path` | `string` | Path to a custom destination folder |
## Languages
Fetch language related resources.
```sh filename="Terminal" copy
playbooks languages
playbooks languages --query next
playbooks languages typescript
playbooks languages typescript open
playbooks languages typescript --include framework
playbooks languages typescript plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Login
Login to Playbooks via email and password.
```sh filename="Terminal" copy
playbooks login
playbooks login --email acme@example.com --password ******
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--email` | `string` | Your email address |
| `--password` | `string` | Your password |
## Register
Create a Playbooks account via name, email, and password.
```sh filename="Terminal" copy
playbooks register
playbooks register --name "Acme Team" --email acme@example.com --password ******
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--name` | `string` | Your name |
| `--email` | `string` | Your email address |
| `--password` | `string` | Your password |
## Logout
Logout of your Playbooks account.
```sh filename="Terminal" copy
playbooks logout
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| None | `—` | No command-specific options |
## MCP
Configure Playbooks MCP for supported coding environments on your local machine.
```sh filename="Terminal" copy
playbooks mcp claude
playbooks mcp codex
playbooks mcp cursor
playbooks mcp vscode
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| None | `—` | No command-specific options |
## OAuth
Login to Playbooks via GitHub OAuth.
```sh filename="Terminal" copy
playbooks oauth
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| None | `—` | No command-specific options |
## Ping
Test your connection to the Playbooks API.
```sh filename="Terminal" copy
playbooks ping
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| None | `—` | No command-specific options |
## Plays
Fetch play related resources.
```sh filename="Terminal" copy
playbooks plays
playbooks plays --query next
playbooks plays --view featured
playbooks plays actix-official-starter
playbooks plays actix-official-starter demo
playbooks plays actix-official-starter deploy
playbooks plays actix-official-starter open
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Platforms
Fetch platform related resources.
```sh filename="Terminal" copy
playbooks platforms
playbooks platforms --query next
playbooks platforms web
playbooks platforms web open
playbooks platforms web --include tool
playbooks platforms web plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Publish
Publish a play to the marketplace.
```sh filename="Terminal" copy
playbooks publish
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| None | `—` | No command-specific options |
## Session
Fetch and display your current session.
```sh filename="Terminal" copy
playbooks session
playbooks session --select 'id,name,uuid,email'
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
## Submit
Submit a play via a GitHub URL.
```sh filename="Terminal" copy
playbooks submit https://github.com/ehubbell/astro-official-starter
playbooks submit https://github.com/ehubbell/astro-official-starter --variant default --visibility public
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--variant` | `string` | Select a variant |
| `--visibility` | `string` | Select a visibility setting |
## Sync
Sync a play to pull the latest files from GitHub.
```sh filename="Terminal" copy
playbooks sync
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| None | `—` | No command-specific options |
## Tags
Fetch tag related resources.
```sh filename="Terminal" copy
playbooks tags
playbooks tags --query next
playbooks tags portfolio
playbooks tags portfolio open
playbooks tags portfolio --include user
playbooks tags portfolio plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Teams
Fetch team related resources.
```sh filename="Terminal" copy
playbooks teams
playbooks teams --query next
playbooks teams mile-hi-labs
playbooks teams mile-hi-labs open
playbooks teams mile-hi-labs --include users
playbooks teams mile-hi-labs plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Tools
Fetch tool related resources.
```sh filename="Terminal" copy
playbooks tools
playbooks tools --query next
playbooks tools stripe
playbooks tools stripe open
playbooks tools stripe --include platform
playbooks tools stripe plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
## Toggle
Toggle your active account.
```sh filename="Terminal" copy
playbooks toggle
playbooks toggle --uuid 'playbooks-community'
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--uuid` | `string` | Account identifier |
## Users
Fetch user related resources.
```sh filename="Terminal" copy
playbooks users
playbooks users --query next
playbooks users ehubbell
playbooks users ehubbell open
playbooks users ehubbell --include teams
playbooks users ehubbell plays --view featured
```
| Option | Type | Description |
| :----- | :--- | :---------- |
| `--select` | `string[]` | A comma separated list of fields you'd like to display |
| `--include` | `string` | A comma separated list of relationships to include |
| `--view` | `string` | Filter by view |
| `--query` | `string` | Filter by a search query |
| `--page` | `number` | Fetch a specific page |
| `--pageSize` | `number` | Fetch a specific page size |
| `--sortProp` | `string` | Sort by a specific property |
| `--sortValue` | `string` | Sort using a specific value |
---
# Examples
Here are a few common Playbooks CLI commands that reflect the current command tree.
---
## Login
Connect the CLI to your Playbooks account.
```sh filename="Terminal" copy
playbooks login
```
---
## Account
View the Playbooks account you're currently connected to.
```sh filename="Terminal" copy
playbooks account
```
---
## Account Invoices
View invoices for the currently active account.
```sh filename="Terminal" copy
playbooks account invoices --page 1 --pageSize 25
```
---
## Account Ledgers
View account ledger activity.
```sh filename="Terminal" copy
playbooks account ledgers --select 'id,amount,type'
```
---
## Search Plays
Search marketplace plays using the shared query option.
```sh filename="Terminal" copy
playbooks plays --query next
```
---
## Download
Download a Playbooks repo to your local machine.
```sh filename="Terminal" copy
playbooks download
```
---
## MCP
Configure Playbooks MCP for your coding client.
```sh filename="Terminal" copy
playbooks mcp codex
```
---
## Logout
Disconnect the CLI from your Playbooks account.
```sh filename="Terminal" copy
playbooks logout
```
## MCP
# Overview
`@playbooks/mcp` exposes Playbooks as MCP tools inside clients like Claude Code, Cursor, Codex, and VS Code.
It wraps the Playbooks CLI, so agents can use the same account, config, and project workflows from chat.
---
## Prerequisites
- Node
- A Playbooks account
- `@playbooks/cli`
- An MCP client like Claude Code, Cursor, Codex, or VS Code
---
## Description
The MCP server does not reimplement Playbooks logic.
It translates MCP tool calls into Playbooks CLI commands.
That gives agents access to common Playbooks workflows such as:
- authentication and session checks
- account and discovery lookups
- local project actions like `download`, `add`, and `clone`
- play lifecycle actions like `submit`, `publish`, `sync`, and `deploy`
By default, it uses the same Playbooks config file as the CLI: `~/.playbooksrc`.
---
# Quick Start
The fastest way to get started is to install the Playbooks CLI, then use its MCP setup helpers.
---
## Installation
```sh filename="Terminal" copy
npm install -g @playbooks/cli
```
---
## Connect A Client
Choose the MCP client you want to use:
```sh filename="Terminal" copy
playbooks mcp claude
playbooks mcp cursor
playbooks mcp codex
playbooks mcp vscode
```
These helpers add `@playbooks/mcp` to the matching client config for you.
---
## Authenticate
Once the client is connected, make sure your Playbooks session is ready:
```sh filename="Terminal" copy
playbooks login
playbooks ping
```
If `playbooks ping` returns a success response, your MCP client should be ready to use in a fresh chat.
---
# Examples
Here are a few simple prompts to try once Playbooks MCP is connected.
---
## Session
```txt filename="Prompt" copy
Show my current Playbooks session and account.
```
---
## Discovery
```txt filename="Prompt" copy
Find a few React or Next.js plays I should look at.
```
---
## Project Actions
```txt filename="Prompt" copy
Download this play into the current project.
```
```txt filename="Prompt" copy
Clone this play to my GitHub account.
```
---
## Play Workflows
```txt filename="Prompt" copy
Sync this play from GitHub and publish the latest version.
```
```txt filename="Prompt" copy
Deploy the demo for this play.
```
If a workflow fails, first verify that your CLI session and config are working with `playbooks login` and `playbooks ping`.
## API
# Overview
Playbooks offers a [REST](https://en.wikipedia.org/wiki/REST) API that'll let you access your account, all your account resources, and perform most tasks such as placing orders or downloading content.
### Description
The Playbooks API let's developers communicate programmatically with our servers in a secure, performant manner.
This way, you can bypass the front-end user experience and craft your own programmatic experience based on your needs.
The Playbooks API follows a predictable, resource-oriented URL pattern and uses standard HTTP response codes, authentication, and verbs.
### Base URL
```sh filename="Terminal" copy
https://api.playbooks.xyz
```
### Client libraries
Playbooks offers an NPM library for terminal access. To learn more, please visit our [CLI docs](https://docs.playbooks.xyz/cli).
```sh filename="Terminal" copy
npm install -g @playbooks/cli
```
### Data Formatting
The Playbooks API follows the [JSON API](https://www.jsonapi.org) spec for incoming / outgoing requests.
That said, we've taken a couple liberties to facilitate a more secure, performant DX in some situations.
So, we encourage you to reference the documentation if something looks out of place -- before contacting support.
### What's Included
The Playbooks API comes with the following:
- [Authentication](/authentication)
- [Accounts](/accounts)
- [Error handling](/errors)
- [Globals](/globals)
- [Pagination](/pagination)
- [Rate limits](/rate-limits)
{/* - [Webhooks](/webhooks) */}
To learn more, please visit the appropriate section.
### Support
If you comes across issues or need help, please contact us via support@playbooks.xyz or reach out via live chat.
---
# Quickstart
To get started with the Playbooks API, you can simply copy / paste the following command in your terminal.
This should return a 200 response as shown.
### Request
```sh filename="Basic Request" copy
curl --location "https://api.playbooks.xyz"
```
### Response
```json filename="Response" copy
{
"status": 200,
"data": {
"message": "All systems are ready."
}
}
```
---
# Authentication
The Playbooks API uses API keys to authenticate requests and grant access to private resources.
To see this in action, simply copy / paste the following command and replace the `` with your credentials.
This should return a 200 response as shown.
### Headers
| Header | Type | Description |
| ------------- | ------ | ---------------------- |
| Authorization | string | Your session JWT token |
### Request
```bash filename="Request" copy
curl
--location "https://api.playbooks.xyz/session"
--header "Authorization: "
```
### Response
```json filename="Response" copy
{
"data": {
"type": "users",
"id": "3",
"attributes": {
"first-name": "Eric",
"last-name": "Hubbell",
"tagline": "Entepreneur // Software Developer",
...
}
},
"included": [],
"meta": {},
}
```
---
# Accounts
The Playbooks API offers the ability to access other accounts (ie teams) associated with your session.
In doing so, you're able to act on their behalf, in accordance with your permissions, by passing an `account` header in your request.
### Headers
| Header | Type | Description |
| ------- | ------ | ----------------------- |
| Account | string | Your account identifier |
### Endpoints
To keep things concise, the Playbooks API offers the following endpoints when using the `account` header:
- `/account`
- `/account/*`
Depending on the `account` header you pass, those endpoints will forward your request to the appropriate resource shown below:
- `/session`
- `/session/*`
- `/session/teams/`
- `/session/teams//*`
To see this in action, simply copy / paste the following commands and replace the display headers with your own credentials.
You should get the same 200 response as shown for both requests.
### Requests
```bash filename="Account Request" copy
curl -L "https://api.playbooks.xyz/account"
--header "Authorization: "
--header "Account: "
```
```bash filename="Session Team Request" copy
curl "https://api.playbooks.xyz/session/teams/"
--header "Authorization: "
--header "Account: "
```
### Response
```json filename="Response" copy
{
"data": {
"type": "teams",
"id": "6",
"attributes": {
"status": "active",
"name": "Mile Hi Labs",
"tagline": "Elevated Software & System Design",
...
}
},
"included": [],
"meta": {},
}
```
### Notes
Note the use of `-L` in the convenience request above. This tells curl to accept / follow the server-side redirect.
---
# Errors
The Playbooks API uses standard [HTTP response codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) to indicate the status of an API request.
When an error occurs, the Playbooks API will return a [JSON API](https://www.jsonapi.org) compliant error for client-side handling.
### Attributes
| Attribute | Type | Description |
| :-------- | :------ | :------------------------------ |
| Status | integer | The HTTP response code |
| Title | string | A title for the error |
| Detail | string | A message describing the error |
| Framework | string | A stacktrace locating the error |
### Request
```bash filename="Request" copy
curl --location "https://api.playbooks.xyz/error"
```
### Response
```json filename="Response" copy
{
"errors": [
{
"status": 404,
"title": "Not Found",
"detail": "Sorry that route doesn't exist.",
"stack": ...
}
]
}
```
---
# Globals
For most endpoints, the Playbooks API will accept the following query parameters to sort and modify your results.
Each resource will then accept table-specific parameters, such as `status=active`, for filtering and other response modifications.
Please review the documentation for each resource to learn more about the table-specific parameters they'll accept.
### Standard Parameters
| Attribute | Type | Description |
| :-------- | :----- | :------------------------------------------------ |
| page | number | Zero indexed page |
| pageSize | number | How many items to return per page |
| sortProp | string | Sort results by a specific property |
| sortValue | string | Sort results by a specific value |
| include | string | Comma separated string of related data to include |
### Resource Specific Parameters
| Attribute | Type | Description |
| :-------- | :----- | :----------------------- |
| Status | string | Filter results by status |
### Examples
```sh filename="Examples" copy
GET "/repos?status=active"
GET "/repos?sortProp=name&sortValue=asc"
GET "/repos?sortProp=name&sortValue=asc&page=0&pageSize=20"
GET "/repos?sortProp=name&sortValue=asc&page=0&pageSize=20&include=framework,language,license"
```
---
# Pagination
Per the [JSON API](https://www.jsonapi.org) spec, Playbooks will return a top-level `meta` object containing pagination data when displaying a list of results.
Per the example, the Playbooks API uses a zero-based index for page data.
---
#### Attributes
| Attribute | Type | Description |
| :----------- | :------ | :----------------------------- |
| Page | integer | The HTTP response code |
| PageSize | integer | A title for the error |
| TotalRecords | integer | A message describing the error |
### Request
```bash filename="Request" copy
curl --location "https://api.playbooks.xyz/repos"
```
### Response
```json filename="Response"
{
"meta": {
"page": 0,
"page-size": 20,
"total-records": 29
},
"data": [
{
"type": "repos",
"id": "73",
"attributes": {
"id": 73,
"status": "active",
"name": "React Template",
"uuid": "react-template",
"tagline": "A basic template for launching React JS projects."
}
},
...
]
}
```
---
# Rate Limits
To maintain performance and platform security, the Playbooks API implements rate limiting across all our partners.
The standard rate limit schedule is 20 requests per minute.
If you exceed this threshold, you'll receive an error and subsequent requests won't be counted.
### Headers
| Header | Type | Description |
| :------------------ | :------ | :---------------------------------------- |
| RateLimit-Limit | integer | The rate limit |
| RateLimit-Policy | string | The rate limit policy |
| RateLimit-Remaining | integer | The number of requests you have remaining |
| RateLimit-Reset | integer | The number of milliseconds before reset |
### Examples
```json filename="Response"
{
"errors": [
{
"status": 429,
"title": "Too many requests",
"detail": "Too many requests. Please try again later.",
"stack": ...
}
]
}
```
## Guides
# Guides Overview
We're currently working on this section. Please come back later or contact support with any questions.