Core Commands
Core commands are the foundation of SuperSmall's functionality, providing repository analysis, context generation, and index management capabilities.
init
Initialize and index a repository for optimized context generation.
Synopsis
supersmall init [options]
Description
The init command analyzes your repository and creates an optimized index containing:
- File structure and metadata
- Symbol definitions (functions, classes, variables)
- Import/export relationships
- Dependency graphs
The index is stored in .supersmall/index.json within your repository.
Options
| Option | Description | Default |
|--------|-------------|---------|
| --languages | Comma-separated list of languages to analyze | swift,typescript,javascript,python,go,rust |
| --force | Force re-indexing even if index exists | false |
| --max-file-size | Maximum file size to analyze (in MB) | 10 |
Examples
#### Basic initialization
supersmall init
#### Initialize specific languages only
supersmall init --languages typescript,javascript
#### Force re-indexing
supersmall init --force
#### Analyze larger files
supersmall init --max-file-size 20
Output
Terminal format shows:
- Progress indicators
- Number of files analyzed
- Symbol count
- Indexing time
JSON format includes:
{
"success": true,
"duration": 45.2,
"fileCount": 156,
"symbolCount": 2341,
"indexPath": "/path/to/repo/.supersmall/index.json"
}
---
query
Generate optimized context for a natural language query.
Synopsis
supersmall query [options]
Description
The query command analyzes your query and generates an optimized context package containing the most relevant:
- Files and their contents
- Symbol definitions
- Dependencies
- Related documentation
Arguments
| Argument | Description |
|----------|-------------|
|
Options
| Option | Description | Default |
|--------|-------------|---------|
| --max-tokens | Maximum context size in tokens | 100000 |
| --threshold | Relevance threshold (0.0-1.0) | 0.5 |
| --include-contents | Include file contents in output | false |
Examples
#### Basic query
supersmall query "How does authentication work?"
#### Query with content
supersmall query "database connection logic" --include-contents
#### Limit context size
supersmall query "user registration flow" --max-tokens 50000
#### Higher relevance threshold
supersmall query "payment processing" --threshold 0.8
Output
Terminal format shows:
- Query summary
- Context statistics
- Relevant files with scores
- Token count and optimization ratio
JSON format includes complete context data:
{
"query": "authentication logic",
"files": [...],
"symbols": [...],
"dependencies": [...],
"tokenCount": 15234,
"optimizationRatio": 0.72,
"relevanceScore": 0.89
}
Relevance Scoring
Files are scored based on:
- Name similarity to query terms
- Symbol name matches
- Import/export relationships
- Code patterns and structure
---
update
Update the repository index with incremental changes.
Synopsis
supersmall update [options]
Description
The update command refreshes your repository index by:
- Detecting modified files (using git)
- Re-analyzing changed files
- Updating symbol definitions
- Refreshing dependency graphs
Options
| Option | Description | Default |
|--------|-------------|---------|
| --incremental | Only update modified files since last index | false |
Examples
#### Full update
supersmall update
#### Incremental update (recommended)
supersmall update --incremental
Performance
Incremental updates are significantly faster:
- Full update: Re-analyzes entire repository
- Incremental: Only processes files changed since last index
Git Integration
When using --incremental, SuperSmall uses git to detect changes:
git diff --name-only HEAD
---
stats
Show comprehensive repository index statistics.
Synopsis
supersmall stats [options]
Description
The stats command displays detailed information about your repository index, including:
- File and symbol counts
- Language breakdown
- Index metadata
- Performance metrics
Options
| Option | Description | Default |
|--------|-------------|---------|
| --detailed | Show detailed statistics breakdown | false |
Examples
#### Basic statistics
supersmall stats
#### Detailed statistics
supersmall stats --detailed
#### JSON output
supersmall stats --output-format json
Output
Basic output includes:
📊 Repository Statistics
━━━━━━━━━━━━━━━━━━━━━
📁 Repository: /path/to/repo
📅 Indexed: Oct 15, 2023, 2:30 PM
📈 Files: 156
🔤 Symbols: 2,341
🌐 Languages: typescript, javascript, python
Detailed output adds:
📝 Language Breakdown:
- typescript: 89 files
- javascript: 45 files
- python: 22 files
🏷️ Symbol Types:
- function: 834
- class: 156
- interface: 203
- variable: 1,148
💾 Index Size: 2.4 MB
⚡ Average query time: 84.5ms
Best Practices
Initialization
1. Run init when starting with a new repository
2. Use --force to rebuild index after major refactoring
3. Limit languages to those actually used in your project
Querying
1. Use specific, descriptive queries for better results
2. Start with lower token limits and increase as needed
3. Use --include-contents only when necessary (increases output size)
Updating
1. Use incremental updates for daily work
2. Run full updates after major dependency changes
3. Set up automated updates in CI/CD pipelines
Performance Tips
1. Exclude large binary files with .gitignore
2. Use language filters to skip irrelevant files
3. Monitor index size with stats command
4. Export and cache indexes for CI/CD workflows