Command Line Tool

Instructed CLI

Import instructions and playlists directly into Claude Code, Gemini CLI, OpenAI Codex, and GitHub Copilot, all from a single command. No copy-pasting, no manual file editing. Just run instructed import and you're ready to go.

~ % instructed import my-instruction

? Which AI tool should this be added to?

❯ Claude Code → CLAUDE.md

Gemini CLI → GEMINI.md

OpenAI Codex → AGENTS.md

GitHub Copilot → copilot-instructions.md

✓ Imported "Code Review Guidelines" → CLAUDE.md

Install Instructed CLI

The CLI ships as a single, self-contained binary. There is no Python, Node.js, pip, or any other runtime to install. Download it once and it's ready to use.

Choose whichever installation method you prefer below. The shell script is the fastest way to get started; Homebrew is ideal if you want automatic updates; and direct download is there if you prefer to manage binaries yourself.

macOS, Linux, WSLRecommended

Run the one-liner below in your terminal. The script detects your OS and architecture (Intel or ARM), downloads the correct binary, and places it on your PATH.

curl -fsSL https://instructed.dev/install.sh | sh

Default install dir: ~/.local/bin · Override with INSTALL_DIR=/custom/path · Auto-updates in the background

Homebrew

If you already use Homebrew, tap the Instructed formula and install. Future updates are handled by brew upgrade.

brew tap instructed/tap
brew install instructed

macOS & Linux · SHA256 checksums verified automatically on install & upgrade

Direct Download

Prefer to manage binaries manually? Download the correct build for your platform from GitHub Releases, make it executable with chmod +x, and move it somewhere on your PATH.

macOS (Apple Silicon)instructed-darwin-arm64

macOS (Intel)instructed-darwin-amd64

Linux (x86_64)instructed-linux-amd64

Linux (ARM64)instructed-linux-arm64

Windows (x86_64)instructed-windows-amd64.exe

Auto-updates: The shell installer checks for new versions in the background. You'll always be on the latest release without running any update command.

Verification: SHA256 checksums are published alongside every release on GitHub so you can independently verify binary integrity.

Quick Start Guide

Go from zero to imported instructions in under a minute. Follow these three steps to authenticate, pick an instruction, and write it to the right config file.

Authenticate with your Instructed account

Run the command below and enter your email and password when prompted. Your refresh token is stored securely in your OS keychain (macOS Keychain, GNOME Keyring, or Windows Credential Vault) and is never written to a plain-text file.

instructed authenticate

Find the instruction or playlist you want to import

Every instruction and playlist on Instructed has a unique ID. You can find it on the instruction page or by using the search command. You can also paste a full Instructed URL instead of an ID.

# Search for public instructions
instructed search "react best practices"

# List your own saved instructions
instructed instructions

# List your playlists
instructed playlists

Import into your project

Run the import command from inside your project directory. The CLI will auto-detect your project root (via .git, package.json, etc.) and write the instruction into the correct config file. If you don't specify a target, it will prompt you to choose one.

# Interactive - choose your target from a menu
instructed import my-instruction-id

# Direct - import to a specific AI tool
instructed import my-instruction-id -t claude

# Import to multiple targets at once
instructed import my-instruction-id -t claude -t gemini

# Import to all supported targets
instructed import my-instruction-id --all

Tip: Use --dry-run on any import command to preview exactly what will be written without modifying any files.

Supported Targets

Instructed CLI writes to the correct configuration file for each AI coding agent. Import to a single tool, a few, or all of them at once with --all.

Each target has a project-level config file (written next to your code) and, where supported, a global config that applies across every project on your machine.

Claude Code

-t claude

Anthropic's coding agent reads project-level and global markdown files.

Project: CLAUDE.md

Global: ~/.claude/CLAUDE.md

Gemini CLI

-t gemini

Google's CLI agent uses GEMINI.md at the project root or in your home directory.

Project: GEMINI.md

Global: ~/.gemini/GEMINI.md

OpenAI Codex

-t codex

OpenAI's Codex agent reads AGENTS.md for custom instructions and rules.

Project: AGENTS.md

Global: ~/.codex/AGENTS.md

GitHub Copilot

-t copilot

Copilot's custom instructions live in the .github directory. No global file.

Project: .github/copilot-instructions.md

Command Reference

A complete list of every command and flag the CLI accepts. All commands support --help for inline documentation.

General

Top-level flags available on every command.

instructed --version

Print the installed CLI version and exit.

instructed --help

Show a summary of all available commands and global flags.

Authentication

Manage your session. Credentials are stored in your operating system's secure keychain, never in plain-text config files.

instructed authenticate

Sign in with your Instructed email and password. A refresh token is saved to your OS keychain (macOS Keychain, GNOME Keyring, or Windows Credential Vault). Short-lived ID tokens are generated on demand and never persisted.

instructed logout

Revoke the current session and remove all stored credentials from the keychain.

instructed whoami

Show the email and display name of the currently authenticated user. Verified server-side, not read from a local cache.

Importing

The core workflow. Import individual instructions or entire playlists into one or more AI tool config files.

instructed import <id>

Import an instruction or playlist interactively. The CLI will prompt you to choose a target if one isn't specified.

instructed import <id> -t claude

Import directly to Claude Code's CLAUDE.md, skipping the interactive prompt.

instructed import <id> -t claude -t gemini

Import to multiple targets in a single command. Each target gets its own config file.

instructed import <id> --all

Import to all four supported targets at once (Claude Code, Gemini CLI, OpenAI Codex, and GitHub Copilot).

instructed import <id> -p "2.24.25-14.30.05"

Pin to a specific published version. Useful for locking instructions across your team.

instructed import <id> --dry-run

Preview the exact content that would be written without modifying any files. Great for reviewing before committing.

instructed import <id> --yes

Skip all interactive confirmations. Useful in CI/CD pipelines or automated scripts.

instructed import <url>

Import by pasting a full Instructed URL (e.g. https://instructed.dev/instructions/abc123). The CLI extracts the ID automatically.

Browse & Search

Discover instructions without leaving your terminal. Results are returned from the Instructed API.

instructed instructions

List all instructions in your account, sorted by last modified. Results are paginated. Use arrow keys to navigate.

instructed playlists

List all playlists in your account with instruction counts and visibility status.

instructed search "code review"

Full-text search across all public instructions. Returns titles, authors, and IDs you can pass straight to import.

instructed status

Show every instruction currently imported in this project, read from the local .instructed.json manifest. Includes version info and target files.

How It Works

Under the hood, the CLI is designed to be safe, predictable, and non-destructive. It never overwrites your existing content. Instead, it appends structured blocks that can be updated or removed cleanly on subsequent runs.

Structured Import Markers

Every imported instruction is wrapped in machine-parseable HTML comment markers that include the source type, unique ID, and version timestamp. These markers let the CLI reliably find, update, and remove imports without touching anything you've written manually. Re-importing the same instruction replaces the existing block in place rather than creating a duplicate.

CLAUDE.md

<!-- instructed:start source=instruction id=abc123 version=2.24.25-14.30.05 -->

## Code Review Guidelines

Always check for error handling, test coverage,
and consistent naming conventions.

<!-- instructed:end id=abc123 -->

The markers are standard HTML comments, invisible to Markdown renderers and AI agents

Atomic Writes

The CLI writes content to a temporary file first, then atomically moves it into place using os.replace. This means your config file is never left in a half-written state. Even if the process is killed mid-write, you'll have either the old file or the new one, never a corrupted mix.

Playlist Resolution

When you import a playlist, a single API call to /resolve returns the full content of every instruction in that playlist. Private instructions you don't have access to are reported as skipped with a clear message. No silent failures or partial imports.

Project Root Detection

The CLI walks up from your current directory looking for common project markers: .git, package.json, pyproject.toml, Cargo.toml, go.mod, and others. Config files are always written relative to the detected root, so you can run the command from any subdirectory.

API-Backed Architecture

All data flows through a single endpoint at api.instructed.dev over HTTPS. The CLI never connects to Firebase or any other backend directly. Authentication, access control, rate limiting, and content validation are all handled server-side.

Security

The CLI is designed with a defense-in-depth approach. Credentials never leave your OS keychain, all network traffic is encrypted, and file writes are atomic. Here's a breakdown of every security layer.

Encrypted Transport

Every request uses HTTPS with TLS certificate verification enforced. The CLI communicates with a single domain (api.instructed.dev). No third-party endpoints are contacted.

OS Keychain Storage

Refresh tokens are stored in your operating system's secure keychain (macOS Keychain, GNOME Keyring, or Windows Credential Vault). Short-lived ID tokens are generated per session and never written to disk.

Content Safety Scanning

Before writing any content, the CLI scans for potentially dangerous patterns like <script> tags, javascript: URIs, and data:text/html payloads. Flagged content triggers a warning; the original content is always preserved verbatim.

Input Validation

Instruction IDs and version strings are validated client-side with strict regex patterns before any API call is made. The server independently validates all input and returns 422 for anything that doesn't match.

Atomic File Writes

All file modifications write to a temporary file first, then atomically replace the target using os.replace. Structured HTML comment markers prevent content injection. Your config files are never left in a corrupted state.

Path Traversal Protection

The ID regex pattern ^[a-zA-Z0-9_-]{1,128}$ strictly blocks directory traversal sequences (../), null bytes, and any special characters that could escape the intended file path.

Rate Limit Handling

The CLI gracefully handles HTTP 429 responses by reading the X-RateLimit-Reset header and waiting the appropriate duration before retrying. No requests are dropped silently.

Binary Integrity

SHA256 checksums are published alongside every release on GitHub. Homebrew formula installations verify checksums automatically. You can also verify manually after a direct download.

Ready to get started?

Install the CLI, authenticate once, and start importing instructions into Claude Code, Gemini, Codex, and Copilot, all from a single command. No Python, Node.js, or any runtime required.

curl -fsSL https://instructed.dev/install.sh | sh

Or install via brew tap instructed/tap && brew install instructed · Available on macOS, Linux, and Windows