Skip to content

Commit 697daec

Browse files
mnriemmnriem
authored
docs: add core commands reference and simplify README CLI section (#2245)
* docs: add core commands reference and simplify README CLI section - New docs/reference/core.md: reference for init (active options only, copilot as main example), check, and version commands - docs/toc.yml: add Core Commands under Reference - README.md: replace verbose CLI Reference section (init options table, 30+ per-agent examples, deprecated flags, env vars) with links to reference docs; use copilot as main example throughout * docs: add CLI reference overview page - New docs/reference/overview.md: explains each CLI surface area (core, integrations, extensions, presets, workflows) with key commands and links to detailed reference pages - docs/toc.yml: add Overview as first item under Reference - README.md: simplify CLI Reference to single link to overview page * docs: remove command references from overview, keep paragraphs only
1 parent 02a1d61 commit 697daec

File tree

4 files changed

+127
-140
lines changed

4 files changed

+127
-140
lines changed

‎README.md‎

Lines changed: 11 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,9 @@ And use the tool directly:
7777
specify init <PROJECT_NAME>
7878

7979
# Or initialize in existing project
80-
specify init . --ai claude
80+
specify init . --ai copilot
8181
# or
82-
specify init --here --ai claude
82+
specify init --here --ai copilot
8383

8484
# Check installed tools
8585
specify check
@@ -100,9 +100,9 @@ Run directly without installing:
100100
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
101101

102102
# Or initialize in existing project
103-
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai claude
103+
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai copilot
104104
# or
105-
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai claude
105+
uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai copilot
106106
```
107107

108108
**Benefits of persistent installation:**
@@ -349,136 +349,7 @@ Additional commands for enhanced quality and validation:
349349

350350
## 🔧 Specify CLI Reference
351351

352-
The `specify` tool is invoked as
353-
354-
```text
355-
specify <COMMAND> [SUBCOMMAND] [OPTIONS]
356-
```
357-
358-
and supports the following commands:
359-
360-
### Commands
361-
362-
| Command | Description |
363-
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364-
| `init` | Initialize a new Specify project from the latest template. |
365-
| `check` | Check for installed tools: `git` plus all CLI-based agents configured in `AGENT_CONFIG` (for example: `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `junie`, `qwen`, `opencode`, `codex`, `kiro-cli`, `shai`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, `forge`, etc.) |
366-
| `version` | Show the currently installed Spec Kit version. |
367-
| `extension` | Manage extensions |
368-
| `preset` | Manage presets |
369-
| `integration` | Manage integrations |
370-
| `workflow` | Run, manage, and search workflows. See the [Workflows reference](https://github.github.io/spec-kit/reference/workflows.html) |
371-
372-
### `specify init` Arguments & Options
373-
374-
```bash
375-
specify init [PROJECT_NAME] <OPTIONS>
376-
```
377-
378-
| Argument/Option | Type | Description |
379-
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
380-
| `<PROJECT_NAME>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
381-
| `--ai` | Option | AI assistant to use (see `AGENT_CONFIG` for the full, up-to-date list). Common options include: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `junie`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `kiro-cli` (`kiro` alias), `agy`, `bob`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, `forge`, or `generic` (requires `--ai-commands-dir`) |
382-
| `--ai-commands-dir` | Option | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`) |
383-
| `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) |
384-
| `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code |
385-
| `--no-git` | Flag | Skip git repository initialization |
386-
| `--here` | Flag | Initialize project in the current directory instead of creating a new one |
387-
| `--force` | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) |
388-
| `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) |
389-
| `--debug` | Flag | Enable detailed debug output for troubleshooting |
390-
| `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) |
391-
| `--ai-skills` | Flag | Install Prompt.MD templates as agent skills in agent-specific `skills/` directory (requires `--ai`). Extension commands are also auto-registered as skills when extensions are added later. |
392-
| `--branch-numbering` | Option | Branch numbering strategy: `sequential` (default — `001`, `002`, `003`, …, `1000`, … — expands beyond 3 digits automatically) or `timestamp` (`YYYYMMDD-HHMMSS`). Timestamp mode is useful for distributed teams to avoid numbering conflicts |
393-
394-
### Examples
395-
396-
```bash
397-
# Basic project initialization
398-
specify init my-project
399-
400-
# Initialize with specific AI assistant
401-
specify init my-project --ai claude
402-
403-
# Initialize with Cursor support
404-
specify init my-project --ai cursor-agent
405-
406-
# Initialize with Qoder support
407-
specify init my-project --ai qodercli
408-
409-
# Initialize with Windsurf support
410-
specify init my-project --ai windsurf
411-
412-
# Initialize with Kiro CLI support
413-
specify init my-project --ai kiro-cli
414-
415-
# Initialize with Amp support
416-
specify init my-project --ai amp
417-
418-
# Initialize with SHAI support
419-
specify init my-project --ai shai
420-
421-
# Initialize with Mistral Vibe support
422-
specify init my-project --ai vibe
423-
424-
# Initialize with IBM Bob support
425-
specify init my-project --ai bob
426-
427-
# Initialize with Pi Coding Agent support
428-
specify init my-project --ai pi
429-
430-
# Initialize with Codex CLI support
431-
specify init my-project --ai codex --ai-skills
432-
433-
# Initialize with Antigravity support
434-
specify init my-project --ai agy --ai-skills
435-
436-
# Initialize with Forge support
437-
specify init my-project --ai forge
438-
439-
# Initialize with an unsupported agent (generic / bring your own agent)
440-
specify init my-project --ai generic --ai-commands-dir .myagent/commands/
441-
442-
# Initialize with PowerShell scripts (Windows/cross-platform)
443-
specify init my-project --ai copilot --script ps
444-
445-
# Initialize in current directory
446-
specify init . --ai copilot
447-
# or use the --here flag
448-
specify init --here --ai copilot
449-
450-
# Force merge into current (non-empty) directory without confirmation
451-
specify init . --force --ai copilot
452-
# or
453-
specify init --here --force --ai copilot
454-
455-
# Skip git initialization
456-
specify init my-project --ai gemini --no-git
457-
458-
# Enable debug output for troubleshooting
459-
specify init my-project --ai claude --debug
460-
461-
# Use GitHub token for API requests (helpful for corporate environments)
462-
specify init my-project --ai claude --github-token ghp_your_token_here
463-
464-
# Claude Code installs skills with the project by default
465-
specify init my-project --ai claude
466-
467-
# Initialize in current directory with agent skills
468-
specify init --here --ai gemini --ai-skills
469-
470-
# Use timestamp-based branch numbering (useful for distributed teams)
471-
specify init my-project --ai claude --branch-numbering timestamp
472-
473-
# Check system requirements
474-
specify check
475-
```
476-
477-
### Environment Variables
478-
479-
| Variable | Description |
480-
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
481-
| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.<br/>\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. |
352+
For full command details, options, and examples, see the [CLI Reference](https://github.github.io/spec-kit/reference/overview.html).
482353

483354
## 🧩 Making Spec Kit Your Own: Extensions & Presets
484355

@@ -627,29 +498,29 @@ specify init --here --force
627498
You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal:
628499

629500
```bash
630-
specify init <project_name> --ai claude
501+
specify init <project_name> --ai copilot
631502
specify init <project_name> --ai gemini
632503
specify init <project_name> --ai copilot
633504

634505
# Or in current directory:
635-
specify init . --ai claude
506+
specify init . --ai copilot
636507
specify init . --ai codex --ai-skills
637508

638509
# or use --here flag
639-
specify init --here --ai claude
510+
specify init --here --ai copilot
640511
specify init --here --ai codex --ai-skills
641512

642513
# Force merge into a non-empty current directory
643-
specify init . --force --ai claude
514+
specify init . --force --ai copilot
644515

645516
# or
646-
specify init --here --force --ai claude
517+
specify init --here --force --ai copilot
647518
```
648519

649520
The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, Pi, Forge, Goose, or Mistral Vibe installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:
650521

651522
```bash
652-
specify init <project_name> --ai claude --ignore-agent-tools
523+
specify init <project_name> --ai copilot --ignore-agent-tools
653524
```
654525

655526
### **STEP 1:** Establish project principles

‎docs/reference/core.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Core Commands
2+
3+
The core `specify` commands handle project initialization, system checks, and version information.
4+
5+
## Initialize a Project
6+
7+
```bash
8+
specify init [<project_name>]
9+
```
10+
11+
| Option | Description |
12+
| ------------------------ | ------------------------------------------------------------------------ |
13+
| `--integration <key>` | AI coding agent integration to use (e.g. `copilot`, `claude`, `gemini`). See the [Integrations reference](integrations.md) for all available keys |
14+
| `--integration-options` | Options for the integration (e.g. `--integration-options="--commands-dir .myagent/cmds"`) |
15+
| `--script sh\|ps` | Script type: `sh` (bash/zsh) or `ps` (PowerShell) |
16+
| `--here` | Initialize in the current directory instead of creating a new one |
17+
| `--force` | Force merge/overwrite when initializing in an existing directory |
18+
| `--no-git` | Skip git repository initialization |
19+
| `--ignore-agent-tools` | Skip checks for AI coding agent CLI tools |
20+
| `--preset <id>` | Install a preset during initialization |
21+
| `--branch-numbering` | Branch numbering strategy: `sequential` (default) or `timestamp` |
22+
23+
Creates a new Spec Kit project with the necessary directory structure, templates, scripts, and AI coding agent integration files.
24+
25+
Use `<project_name>` to create a new directory, or `--here` (or `.`) to initialize in the current directory. If the directory already has files, use `--force` to merge without confirmation.
26+
27+
### Examples
28+
29+
```bash
30+
# Create a new project with an integration
31+
specify init my-project --integration copilot
32+
33+
# Initialize in the current directory
34+
specify init --here --integration copilot
35+
36+
# Force merge into a non-empty directory
37+
specify init --here --force --integration copilot
38+
39+
# Use PowerShell scripts (Windows/cross-platform)
40+
specify init my-project --integration copilot --script ps
41+
42+
# Skip git initialization
43+
specify init my-project --integration copilot --no-git
44+
45+
# Install a preset during initialization
46+
specify init my-project --integration copilot --preset compliance
47+
48+
# Use timestamp-based branch numbering (useful for distributed teams)
49+
specify init my-project --integration copilot --branch-numbering timestamp
50+
```
51+
52+
### Environment Variables
53+
54+
| Variable | Description |
55+
| ----------------- | ------------------------------------------------------------------------ |
56+
| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches. Must be set in the context of the agent prior to using `/speckit.plan` or follow-up commands. |
57+
58+
## Check Installed Tools
59+
60+
```bash
61+
specify check
62+
```
63+
64+
Checks that required tools are available on your system: `git` and any CLI-based AI coding agents. IDE-based agents are skipped since they don't require a CLI tool.
65+
66+
## Version Information
67+
68+
```bash
69+
specify version
70+
```
71+
72+
Displays the Spec Kit CLI version, Python version, platform, and architecture.
73+
74+
A quick version check is also available via:
75+
76+
```bash
77+
specify --version
78+
specify -V
79+
```

0 commit comments

Comments
 (0)