# Specsmith CLI
> **Forge clear specifications from product ideas.**
> *AI-powered agent for developers and builders.*
[](https://badge.fury.io/py/specsmith-cli)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
The Specsmith CLI is a thin client for AI-powered specification generation using the Specsmith platform. Run `specsmith`, describe what you need, and get structured, implementation-ready technical specs.
## 🚀 What is Specsmith?
Specsmith helps engineers move from rough ideas to actionable specifications. It asks clarifying questions, identifies ambiguities, and produces detailed specs designed to feed directly into AI coding agents or human implementation.
### ✨ Key Capabilities
* **🧠 Structured Specs**: From natural language to clear acceptance criteria & Definition of Done
* **💬 Clarifying Conversations**: Interactive chat that refines requirements before finalizing
* **📁 File Handling**: Create and update spec files right from the CLI
* **⚡ Streaming Responses**: Real-time feedback as the AI reasons through your request
* **🎯 Simple Entry Point**: Just run `specsmith` — no flags required
## 🎯 Perfect For
* Product managers defining features
* Engineers planning implementations
* Architects documenting systems
* DevOps & infra teams writing technical runbooks
## 📦 Installation
```bash
pip install specsmith-cli
specsmith --version
```
## ⚡ Quickstart
### 1. Get Your API Keys
Learn more at [specsmith.ai](https://specsmith.ai) or go straight to [signup](https://app.specsmith.ai/signup) → **Settings** → **API Keys** → generate a new key pair.
### 2. Configure Authentication
Recommended:
```bash
specsmith setup
```
Advanced alternatives:
* **Env vars**
```bash
export SPECSMITH_ACCESS_KEY_ID="your-access-key-id"
export SPECSMITH_ACCESS_KEY_TOKEN="your-access-key-token"
```
* **Config file**
```bash
mkdir -p ~/.specsmith
cat > ~/.specsmith/credentials << EOF
access_key_id=your-access-key-id
access_key_token=your-access-key-token
EOF
```
### 3. Test
```bash
specsmith test
```
### 4. Start Workinggit add 0p
```bash
specsmith
```
That’s it — describe what you need, and specsmith will generate detailed specifications.
## 🎨 Usage Examples
Interactive session:
```bash
specsmith
```
Example:
```
You: I need a real-time chat app
specsmith: Let’s cover scale, features, tech stack, and platforms.
...
```
File management:
```bash
# Inside a chat session
# ✓ Create new file: database-schema.sql? (y/n): y
```
Configuration:
```bash
specsmith config
```
## 🛠️ Advanced Features
* **Custom API Endpoint**
```bash
export SPECSMITH_API_URL="https://your.company/api"
```
* **Debug Mode**
```bash
specsmith --debug
```
* **Available Commands**
```bash
specsmith chat # start chat (default)
specsmith setup # configure credentials
specsmith test # test connection
specsmith config # show current config
specsmith version # version info
specsmith --help # all options
```
## 🔧 Configuration Options
| Variable | Description | Default |
| ---------------------------- | -------------------- | -------------------------- |
| `SPECSMITH_ACCESS_KEY_ID` | API key ID | required |
| `SPECSMITH_ACCESS_KEY_TOKEN` | API key token | required |
| `SPECSMITH_API_URL` | API endpoint | `https://api.specsmith.ai` |
| `SPECSMITH_DEBUG` | Enable debug logging | `false` |
Config sources (priority order):
1. `~/.specsmith/credentials`
2. Env vars
3. CLI args
## 🚀 Real-World Use Cases
```bash
specsmith
# "Plan a notification system for a mobile app with push + email"
```
```bash
specsmith
# "Design a REST API for a multi-tenant SaaS with RBAC"
```
```bash
specsmith
# "Specify a CI/CD pipeline for microservices on Kubernetes"
```
```bash
specsmith
# "Create a database schema for a social app with posts, comments, likes"
```
## 🔍 Troubleshooting
**Auth Errors**
```bash
specsmith test
specsmith setup
```
**Connection Issues**
```bash
curl -I https://api.specsmith.ai/health
specsmith test --debug
```
**File Permissions**
```bash
chmod 755 .
```
More help:
* Docs: [README](https://github.com/specsmith-ai/specsmith-cli#readme)
* Issues: [GitHub](https://github.com/specsmith-ai/specsmith-cli/issues)
* Website: [specsmith.ai](https://specsmith.ai)
* Signup: [app.specsmith.ai/signup](https://app.specsmith.ai/signup)
* Support: [support@specsmith.ai](mailto:support@specsmith.ai)
## 📄 License
MIT License — see [LICENSE](LICENSE)
## 🌟 Why specsmith?
Good code starts with good specs. specsmith makes your requirements:
* **Complete**: No missing edge cases
* **Actionable**: Ready for humans or AI agents
* **Consistent**: Following best practices & standards
* **Contextual**: Informed by your repo & architecture
**Transform your workflow. Start with better specs.**
---
<div align="center">
**[Get Started](https://specsmith.ai)** • **[Signup](https://app.specsmith.ai/signup)** • **[Docs](https://github.com/specsmith-ai/specsmith-cli#readme)**
Made with ❤️ by specsmith
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "specsmith-cli",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "cli, ai, chat, code-generation, specsmith, assistant, automation",
"author": "SpecSmith Team",
"author_email": "team@specsmith.ai",
"download_url": "https://files.pythonhosted.org/packages/03/a6/484ac6b64c6373ef918579bddbdd7cbdfe6a638720a3ec648777ead5570f/specsmith_cli-0.1.5.tar.gz",
"platform": null,
"description": "# Specsmith CLI\n\n> **Forge clear specifications from product ideas.**\n> *AI-powered agent for developers and builders.*\n\n[](https://badge.fury.io/py/specsmith-cli)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nThe Specsmith CLI is a thin client for AI-powered specification generation using the Specsmith platform. Run `specsmith`, describe what you need, and get structured, implementation-ready technical specs.\n\n## \ud83d\ude80 What is Specsmith?\n\nSpecsmith helps engineers move from rough ideas to actionable specifications. It asks clarifying questions, identifies ambiguities, and produces detailed specs designed to feed directly into AI coding agents or human implementation.\n\n### \u2728 Key Capabilities\n\n* **\ud83e\udde0 Structured Specs**: From natural language to clear acceptance criteria & Definition of Done\n* **\ud83d\udcac Clarifying Conversations**: Interactive chat that refines requirements before finalizing\n* **\ud83d\udcc1 File Handling**: Create and update spec files right from the CLI\n* **\u26a1 Streaming Responses**: Real-time feedback as the AI reasons through your request\n* **\ud83c\udfaf Simple Entry Point**: Just run `specsmith` \u2014 no flags required\n\n## \ud83c\udfaf Perfect For\n\n* Product managers defining features\n* Engineers planning implementations\n* Architects documenting systems\n* DevOps & infra teams writing technical runbooks\n\n## \ud83d\udce6 Installation\n\n```bash\npip install specsmith-cli\nspecsmith --version\n```\n\n## \u26a1 Quickstart\n\n### 1. Get Your API Keys\n\nLearn more at [specsmith.ai](https://specsmith.ai) or go straight to [signup](https://app.specsmith.ai/signup) \u2192 **Settings** \u2192 **API Keys** \u2192 generate a new key pair.\n\n### 2. Configure Authentication\n\nRecommended:\n\n```bash\nspecsmith setup\n```\n\nAdvanced alternatives:\n\n* **Env vars**\n\n ```bash\n export SPECSMITH_ACCESS_KEY_ID=\"your-access-key-id\"\n export SPECSMITH_ACCESS_KEY_TOKEN=\"your-access-key-token\"\n ```\n* **Config file**\n\n ```bash\n mkdir -p ~/.specsmith\n cat > ~/.specsmith/credentials << EOF\n access_key_id=your-access-key-id\n access_key_token=your-access-key-token\n EOF\n ```\n\n### 3. Test\n\n```bash\nspecsmith test\n```\n\n### 4. Start Workinggit add 0p\n\n\n```bash\nspecsmith\n```\n\nThat\u2019s it \u2014 describe what you need, and specsmith will generate detailed specifications.\n\n## \ud83c\udfa8 Usage Examples\n\nInteractive session:\n\n```bash\nspecsmith\n```\n\nExample:\n\n```\nYou: I need a real-time chat app\n\nspecsmith: Let\u2019s cover scale, features, tech stack, and platforms.\n...\n```\n\nFile management:\n\n```bash\n# Inside a chat session\n# \u2713 Create new file: database-schema.sql? (y/n): y\n```\n\nConfiguration:\n\n```bash\nspecsmith config\n```\n\n## \ud83d\udee0\ufe0f Advanced Features\n\n* **Custom API Endpoint**\n\n ```bash\n export SPECSMITH_API_URL=\"https://your.company/api\"\n ```\n\n* **Debug Mode**\n\n ```bash\n specsmith --debug\n ```\n\n* **Available Commands**\n\n ```bash\n specsmith chat # start chat (default)\n specsmith setup # configure credentials\n specsmith test # test connection\n specsmith config # show current config\n specsmith version # version info\n specsmith --help # all options\n ```\n\n## \ud83d\udd27 Configuration Options\n\n| Variable | Description | Default |\n| ---------------------------- | -------------------- | -------------------------- |\n| `SPECSMITH_ACCESS_KEY_ID` | API key ID | required |\n| `SPECSMITH_ACCESS_KEY_TOKEN` | API key token | required |\n| `SPECSMITH_API_URL` | API endpoint | `https://api.specsmith.ai` |\n| `SPECSMITH_DEBUG` | Enable debug logging | `false` |\n\nConfig sources (priority order):\n\n1. `~/.specsmith/credentials`\n2. Env vars\n3. CLI args\n\n## \ud83d\ude80 Real-World Use Cases\n\n```bash\nspecsmith\n# \"Plan a notification system for a mobile app with push + email\"\n```\n\n```bash\nspecsmith\n# \"Design a REST API for a multi-tenant SaaS with RBAC\"\n```\n\n```bash\nspecsmith\n# \"Specify a CI/CD pipeline for microservices on Kubernetes\"\n```\n\n```bash\nspecsmith\n# \"Create a database schema for a social app with posts, comments, likes\"\n```\n\n## \ud83d\udd0d Troubleshooting\n\n**Auth Errors**\n\n```bash\nspecsmith test\nspecsmith setup\n```\n\n**Connection Issues**\n\n```bash\ncurl -I https://api.specsmith.ai/health\nspecsmith test --debug\n```\n\n**File Permissions**\n\n```bash\nchmod 755 .\n```\n\nMore help:\n\n* Docs: [README](https://github.com/specsmith-ai/specsmith-cli#readme)\n* Issues: [GitHub](https://github.com/specsmith-ai/specsmith-cli/issues)\n* Website: [specsmith.ai](https://specsmith.ai)\n* Signup: [app.specsmith.ai/signup](https://app.specsmith.ai/signup)\n* Support: [support@specsmith.ai](mailto:support@specsmith.ai)\n\n## \ud83d\udcc4 License\n\nMIT License \u2014 see [LICENSE](LICENSE)\n\n## \ud83c\udf1f Why specsmith?\n\nGood code starts with good specs. specsmith makes your requirements:\n\n* **Complete**: No missing edge cases\n* **Actionable**: Ready for humans or AI agents\n* **Consistent**: Following best practices & standards\n* **Contextual**: Informed by your repo & architecture\n\n**Transform your workflow. Start with better specs.**\n\n---\n\n<div align=\"center\">\n\n**[Get Started](https://specsmith.ai)** \u2022 **[Signup](https://app.specsmith.ai/signup)** \u2022 **[Docs](https://github.com/specsmith-ai/specsmith-cli#readme)**\n\nMade with \u2764\ufe0f by specsmith\n\n</div>\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Official command line interface for SpecSmith - AI-powered code generation and documentation",
"version": "0.1.5",
"project_urls": {
"Documentation": "https://github.com/specsmith-ai/specsmith-cli#readme",
"Homepage": "https://specsmith.ai",
"Repository": "https://github.com/specsmith-ai/specsmith-cli"
},
"split_keywords": [
"cli",
" ai",
" chat",
" code-generation",
" specsmith",
" assistant",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "018a37a89e099df5a0218b7ccec6c6ed5772cc9ee25ac5a509b624cbdfdfcc33",
"md5": "dc0636b9e346ef2b0fcc5f1ddc3cd256",
"sha256": "334508df011b81ae24a1d61d2734f4e885c5f87691c9e21a9a85493155dce9e8"
},
"downloads": -1,
"filename": "specsmith_cli-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc0636b9e346ef2b0fcc5f1ddc3cd256",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 15656,
"upload_time": "2025-09-02T13:34:10",
"upload_time_iso_8601": "2025-09-02T13:34:10.523813Z",
"url": "https://files.pythonhosted.org/packages/01/8a/37a89e099df5a0218b7ccec6c6ed5772cc9ee25ac5a509b624cbdfdfcc33/specsmith_cli-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "03a6484ac6b64c6373ef918579bddbdd7cbdfe6a638720a3ec648777ead5570f",
"md5": "f91ee90a6ccb54fb8625c16a9125e9e0",
"sha256": "ce62570839f91d034288218643817d9a64fbb905278c318c0cf9dfad9ad0b7a2"
},
"downloads": -1,
"filename": "specsmith_cli-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "f91ee90a6ccb54fb8625c16a9125e9e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 14815,
"upload_time": "2025-09-02T13:34:12",
"upload_time_iso_8601": "2025-09-02T13:34:12.835850Z",
"url": "https://files.pythonhosted.org/packages/03/a6/484ac6b64c6373ef918579bddbdd7cbdfe6a638720a3ec648777ead5570f/specsmith_cli-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 13:34:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "specsmith-ai",
"github_project": "specsmith-cli#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "specsmith-cli"
}
JSON
