DeepSeek CLI Usage Guide

Comprehensive guide to using DeepSeek CLI for AI-powered development

Quick Start • Commands • Examples • Configuration • Advanced Usage • Troubleshooting

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/fenwii/deepseek-cli.git
cd deepseek-cli

# Quick start (recommended)
./quickstart.sh

# Or manual installation
./install.sh

2. Configuration

Set your DeepSeek API key:

deepseek config --set apiKey=YOUR_API_KEY

3. Test Connection

deepseek test

4. Start Using

# Interactive chat
deepseek chat

# Analyze codebase
deepseek analyze . --recursive

# Run workflows
deepseek workflow "Help me improve this code"

📋 Commands Reference

Interactive Chat

Start an interactive chat session with DeepSeek AI.

Basic Usage

deepseek chat

Options

-s, --system <prompt>: Set custom system prompt
-f, --file <path>: Load context from file
-m, --model <model>: Specify model (v3, r1, v3-32k, r1-32k)

Examples

# Basic chat
deepseek chat

# With custom system prompt
deepseek chat --system "You are a Python expert specializing in data science"

# With context file
deepseek chat --file context.txt --system "Analyze this codebase"

# Using specific model
deepseek chat --model r1 --system "Provide quick code reviews"

Interactive Commands

exit: Exit the chat session
model: Switch between available models
clear: Clear chat history
help: Show available commands

Code Analysis

Analyze codebases for insights, quality metrics, and recommendations.

Basic Usage

deepseek analyze [path]

Options

-r, --recursive: Analyze subdirectories recursively
-e, --extensions <extensions>: File extensions to include (comma-separated)
-m, --model <model>: Specify model for AI analysis

Examples

# Analyze current directory
deepseek analyze

# Analyze specific path
deepseek analyze src/

# Recursive analysis
deepseek analyze . --recursive

# Focus on specific languages
deepseek analyze src/ --recursive --extensions ts,js,py

# Using specific model for analysis
deepseek analyze . --recursive --model v3-32k

Analysis Output

The analysis provides:

File Statistics: Number of files, total lines, language distribution
Complexity Metrics: Average and maximum complexity scores
AI Insights: AI-powered observations about code quality
Recommendations: Actionable improvement suggestions

Workflow Automation

Execute AI-powered workflows for complex tasks.

Basic Usage

deepseek workflow <task>

Options

-i, --interactive: Enable interactive mode
-o, --output <format>: Output format (json, text, markdown)
-m, --model <model>: Specify model for workflow execution

Examples

# Generate documentation
deepseek workflow "Create comprehensive documentation for this project"

# Security review
deepseek workflow "Review this codebase for security vulnerabilities" --interactive

# Code refactoring
deepseek workflow "Refactor complex functions for better maintainability"

# Generate tests
deepseek workflow "Create unit tests for all functions in src/"

# Performance optimization
deepseek workflow "Identify performance bottlenecks and suggest optimizations"

Interactive Workflows

When using --interactive, you can:

Approve or reject workflow steps
Modify step parameters
Add custom steps
Review results before proceeding

Configuration Management

Manage DeepSeek CLI configuration settings.

Commands

# Set configuration value
deepseek config --set <key>=<value>

# Get configuration value
deepseek config --get <key>

# List all configuration
deepseek config --list

# Reset to defaults
deepseek config --reset

Examples

# Set API key
deepseek config --set apiKey=YOUR_API_KEY

# Set default model
deepseek config --set defaultModel=v3

# Set theme
deepseek config --set theme=dark

# Set token limit
deepseek config --set maxTokens=8000

# View all settings
deepseek config --list

# Get specific value
deepseek config --get apiKey

Model Information

View available DeepSeek models and their capabilities.

deepseek models

Connection Testing

Test DeepSeek API connection and view available models.

deepseek test

📚 Examples

Code Review & Analysis

Comprehensive Codebase Analysis

# Full codebase analysis
deepseek analyze . --recursive

# Focus on specific file types
deepseek analyze src/ --extensions ts,js,py --recursive

# Generate detailed quality report
deepseek workflow "Analyze code quality and generate improvement recommendations"

Language-Specific Analysis

# TypeScript analysis
deepseek analyze src/ --extensions ts --recursive

# Python analysis
deepseek analyze . --extensions py --recursive

# JavaScript analysis
deepseek analyze . --extensions js,jsx --recursive

Performance Analysis

# Identify performance issues
deepseek workflow "Analyze code for performance bottlenecks"

# Optimization suggestions
deepseek workflow "Suggest performance optimizations for this codebase"

Documentation Generation

Project Documentation

# Generate README
deepseek workflow "Create a professional README.md for this project"

# Generate API documentation
deepseek workflow "Generate API documentation for all TypeScript interfaces"

# Create user guides
deepseek workflow "Create user documentation and installation guides"

Code Documentation

# Add JSDoc comments
deepseek workflow "Add comprehensive JSDoc comments to all functions"

# Generate inline documentation
deepseek workflow "Add inline comments explaining complex logic"

Code Migration & Refactoring

Language Migration

# JavaScript to TypeScript
deepseek workflow "Help migrate this JavaScript codebase to TypeScript"

# Python version upgrade
deepseek workflow "Update Python code to use modern syntax and features"

Code Refactoring

# Refactor complex functions
deepseek workflow "Refactor high-complexity functions for better maintainability"

# Improve code structure
deepseek workflow "Restructure code for better organization and readability"

Dependency Management

# Update dependencies
deepseek workflow "Analyze package.json and suggest dependency updates"

# Security audit
deepseek workflow "Check for security vulnerabilities in dependencies"

Testing & Quality Assurance

Test Generation

# Generate unit tests
deepseek workflow "Create comprehensive unit tests for all functions"

# Generate integration tests
deepseek workflow "Create integration tests for API endpoints"

# Generate test documentation
deepseek workflow "Create testing documentation and examples"

Quality Assurance

# Code coverage analysis
deepseek workflow "Analyze test coverage and suggest improvements"

# Code style review
deepseek workflow "Review code style and suggest formatting improvements"

# Best practices check
deepseek workflow "Check code against industry best practices"

DevOps & CI/CD

Pipeline Integration

# Generate CI/CD configuration
deepseek workflow "Create GitHub Actions workflow for this project"

# Docker configuration
deepseek workflow "Create Dockerfile and docker-compose.yml for this application"

# Deployment scripts
deepseek workflow "Create deployment scripts and documentation"

Monitoring & Logging

# Add logging
deepseek workflow "Add comprehensive logging to all functions"

# Error handling
deepseek workflow "Improve error handling and add proper error messages"

# Monitoring setup
deepseek workflow "Suggest monitoring and alerting setup for this application"

⚙️ Configuration

Environment Variables

Variable	Description	Default	Example
`DEEPSEEK_API_KEY`	Your DeepSeek API key	-	`sk-1234567890abcdef`
`DEEPSEEK_MODEL`	Default model	v3	`v3`, `r1`, `v3-32k`, `r1-32k`
`DEEPSEEK_THEME`	Color theme	auto	`light`, `dark`, `auto`
`DEEPSEEK_MAX_TOKENS`	Max tokens per request	4000	`8000`
`DEEPSEEK_TEMPERATURE`	Response temperature	0.7	`0.5`
`DEEPSEEK_TIMEOUT`	Request timeout (ms)	60000	`120000`
`DEEPSEEK_LOG_LEVEL`	Logging level	info	`debug`, `info`, `warn`, `error`

Configuration File

Located at ~/.deepseek-cli/config.json:

{
  "apiKey": "your-api-key",
  "defaultModel": "v3",
  "theme": "auto",
  "enableLogging": false,
  "maxTokens": 4000,
  "temperature": 0.7,
  "timeout": 60000,
  "autoSave": true,
  "workspace": "./",
  "customPrompts": {
    "code_review": "You are an expert code reviewer. Analyze the code for bugs, performance issues, and best practices.",
    "documentation": "You are a technical writer. Create clear, comprehensive documentation for the code.",
    "testing": "You are a testing expert. Generate comprehensive test cases for the code.",
    "security": "You are a security expert. Review code for security vulnerabilities and best practices.",
    "performance": "You are a performance optimization expert. Analyze code for performance bottlenecks."
  }
}

Custom Prompts

You can define custom prompts for specific use cases:

# Set custom prompt
deepseek config --set customPrompts.code_review="You are a senior developer..."

# Use custom prompt in chat
deepseek chat --system "$(deepseek config --get customPrompts.code_review)"

🤖 Models

DeepSeek V3 (Recommended)

Best for: Most general tasks, code analysis, documentation
Performance: Balanced speed and quality
Context: 4K tokens
Use cases: Code review, documentation, general assistance
Cost: Standard pricing

DeepSeek R1 (Fast)

Best for: Quick tasks, simple queries
Performance: Fastest response times
Context: 4K tokens
Use cases: Quick questions, simple code analysis
Cost: Lower pricing

DeepSeek V3-32K (Long Context)

Best for: Large codebases, complex analysis
Performance: Slower but more comprehensive
Context: 32K tokens
Use cases: Large file analysis, complex workflows
Cost: Higher pricing

DeepSeek R1-32K (Fast Long Context)

Best for: Large codebases with quick responses
Performance: Fast with long context
Context: 32K tokens
Use cases: Large codebases, quick analysis
Cost: Higher pricing

Model Selection Guide

Task Type	Recommended Model	Reason
Quick questions	R1	Fastest response
Code review	V3	Best quality
Documentation	V3	Comprehensive output
Large files	V3-32K	Long context needed
Simple analysis	R1	Cost-effective
Complex workflows	V3-32K	Detailed processing

🔧 Advanced Usage

Custom Workflows

Create and execute custom workflow templates:

# Save workflow to file
deepseek workflow "Generate API client" --output json > api-client-workflow.json

# Execute from file
deepseek workflow api-client-workflow.json

# Create reusable workflow
cat > my-workflow.json << EOF
{
  "name": "Code Review Workflow",
  "steps": [
    {
      "type": "ai_task",
      "name": "Analyze Code Quality",
      "description": "Review code for quality issues"
    },
    {
      "type": "ai_task", 
      "name": "Generate Recommendations",
      "description": "Create improvement suggestions"
    }
  ]
}
EOF

deepseek workflow my-workflow.json

Integration with CI/CD

GitHub Actions

name: Code Analysis
on: [push, pull_request]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g @fenwii/deepseek-cli
      - run: |
          deepseek config --set apiKey=${{ secrets.DEEPSEEK_API_KEY }}
          deepseek analyze . --recursive --extensions js,ts

GitLab CI

code_analysis:
  image: node:18
  script:
    - npm install -g @fenwii/deepseek-cli
    - deepseek config --set apiKey=$DEEPSEEK_API_KEY
    - deepseek analyze . --recursive

Scripting & Automation

Automated Code Review

#!/bin/bash
# automated-review.sh

echo "🔍 Starting automated code review..."

# Analyze codebase
deepseek analyze . --recursive > analysis-report.txt

# Generate recommendations
deepseek workflow "Review the analysis report and suggest improvements" \
  --file analysis-report.txt > recommendations.txt

# Create summary
echo "📊 Code Review Summary" > summary.md
echo "=====================" >> summary.md
echo "" >> summary.md
echo "## Analysis Results" >> summary.md
cat analysis-report.txt >> summary.md
echo "" >> summary.md
echo "## Recommendations" >> summary.md
cat recommendations.txt >> summary.md

echo "✅ Code review completed! Check summary.md for results."

Batch Processing

#!/bin/bash
# batch-analyze.sh

for dir in */; do
  if [ -d "$dir" ]; then
    echo "Analyzing $dir..."
    deepseek analyze "$dir" --recursive > "${dir%/}-analysis.txt"
  fi
done

File Context Loading

Load context from various file types:

# Load from text file
deepseek chat --file context.txt

# Load from JSON file
deepseek chat --file config.json

# Load from code file
deepseek chat --file src/main.ts

# Load from multiple files
cat file1.txt file2.txt > combined.txt
deepseek chat --file combined.txt

Output Formats

JSON Output

# Get structured data
deepseek analyze . --recursive --output json > analysis.json

# Process with jq
deepseek analyze . --recursive --output json | jq '.filesAnalyzed'

Markdown Output

# Generate markdown report
deepseek workflow "Create documentation" --output markdown > docs.md

# Include in README
deepseek workflow "Generate README section" --output markdown >> README.md

🐛 Troubleshooting

Common Issues

API Key Issues

# Check if API key is set
deepseek config --get apiKey

# Set API key
deepseek config --set apiKey=YOUR_API_KEY

# Test connection
deepseek test

# Verify API key format
# Should start with 'sk-' and be 32+ characters

Permission Issues

# Fix global installation permissions
sudo yarn global add .

# Or use local installation
yarn link

# Check file permissions
ls -la ~/.deepseek-cli/

# Fix configuration directory permissions
chmod 755 ~/.deepseek-cli/
chmod 600 ~/.deepseek-cli/config.json

Build Issues

# Clean and rebuild
yarn clean
yarn install
yarn build

# Check Node.js version
node --version  # Should be 18+

# Check TypeScript compilation
yarn tsc --noEmit

# Check for missing dependencies
yarn install --force

Network Issues

# Test internet connection
curl -I https://api.deepseek.com

# Check proxy settings
echo $http_proxy
echo $https_proxy

# Test with verbose logging
deepseek test --verbose

Error Messages

"API connection failed"

Check your internet connection
Verify API key is correct
Check if DeepSeek API is accessible from your location
Try with --verbose flag for more details

"File does not exist"

Verify file path is correct
Check file permissions
Use absolute paths if needed

"Model not found"

Check available models: deepseek models
Verify model name spelling
Try with default model: deepseek config --set defaultModel=v3

"Timeout error"

Increase timeout: deepseek config --set timeout=120000
Check network connection
Try with smaller files or simpler requests

Performance Optimization

Reduce Response Time

# Use faster model
deepseek config --set defaultModel=r1

# Reduce token limit
deepseek config --set maxTokens=2000

# Use local caching
deepseek config --set enableCaching=true

Handle Large Codebases

# Analyze in chunks
deepseek analyze src/ --extensions ts
deepseek analyze src/ --extensions js
deepseek analyze src/ --extensions py

# Use 32K model for large files
deepseek analyze . --recursive --model v3-32k

Getting Help

Command Help

# General help
deepseek --help

# Command-specific help
deepseek chat --help
deepseek analyze --help
deepseek workflow --help
deepseek config --help

Debug Mode

# Enable verbose logging
deepseek config --set enableLogging=true

# Run with debug output
deepseek test --verbose

# Check logs
tail -f ~/.deepseek-cli/logs/deepseek.log

Community Support

📖 Best Practices

1. Model Selection

Use R1 for quick questions and simple tasks
Use V3 for code review and documentation
Use 32K variants for large files and complex analysis
Consider cost vs. performance trade-offs

2. Configuration Management

Store API key securely (environment variables preferred)
Use custom prompts for consistent results
Set appropriate timeouts for your use case
Enable logging for debugging

3. Code Analysis

Analyze specific directories rather than entire codebase
Use file extensions to focus on relevant languages
Review AI recommendations before implementing
Combine with other static analysis tools

4. Workflow Design

Break complex tasks into smaller steps
Use interactive mode for important decisions
Save and reuse successful workflows
Validate workflow outputs

5. Security

Never commit API keys to version control
Use environment variables for sensitive data
Regularly rotate API keys
Monitor API usage and costs

6. Performance

Use appropriate models for task complexity
Cache frequently used results
Batch similar requests when possible
Monitor response times and optimize

🔮 Future Features

Planned Enhancements

Plugin System: Extend functionality with custom plugins
Team Collaboration: Share workflows and configurations
Advanced Analytics: Detailed usage analytics and insights
IDE Integration: Direct integration with popular IDEs
Cloud Sync: Synchronize configurations across devices

Contributing

We welcome contributions! See our Contributing Guide for details.

Need help? Open an Issue • Join Discussions

Author: samir.tan.it@gmail.com
Created: 2025-06-28
Last Updated: 2025-06-28
Version: 1.0.0

FilesExpand file tree

USAGE_GUIDE.md

Latest commit

History

USAGE_GUIDE.md

File metadata and controls

DeepSeek CLI Usage Guide

🚀 Quick Start

1. Installation

2. Configuration

3. Test Connection

4. Start Using

📋 Commands Reference

Interactive Chat

Basic Usage

Options

Examples

Interactive Commands

Code Analysis

Basic Usage

Options

Examples

Analysis Output

Workflow Automation

Basic Usage

Options

Examples

Interactive Workflows

Configuration Management

Commands

Examples

Model Information

Connection Testing

📚 Examples

Code Review & Analysis

Comprehensive Codebase Analysis

Language-Specific Analysis

Performance Analysis

Documentation Generation

Project Documentation

Code Documentation

Code Migration & Refactoring

Language Migration

Code Refactoring

Dependency Management

Testing & Quality Assurance

Test Generation

Quality Assurance

DevOps & CI/CD

Pipeline Integration

Monitoring & Logging

⚙️ Configuration

Environment Variables

Configuration File

Custom Prompts

🤖 Models

DeepSeek V3 (Recommended)

DeepSeek R1 (Fast)

DeepSeek V3-32K (Long Context)

DeepSeek R1-32K (Fast Long Context)

Model Selection Guide

🔧 Advanced Usage

Custom Workflows

Integration with CI/CD

GitHub Actions

GitLab CI

Scripting & Automation

Automated Code Review

Batch Processing

File Context Loading

Output Formats

JSON Output

Markdown Output

🐛 Troubleshooting

Common Issues

API Key Issues

Permission Issues

Build Issues

Network Issues

Error Messages