cst
codestory: Give your project a good story worth reading
Usage
cst [OPTIONS] COMMAND [ARGS]...
Arguments
No arguments available
Options
| Name | Description | Required | Default |
|---|---|---|---|
-V, --version |
Show version and exit | No | - |
-LD, --log-dir |
Show log path (where logs for codestory live) and exit | No | - |
-SL, --supported-languages |
Show languages that support semantic analysis and grouping, then exit | No | - |
-SP, --supported-providers |
Show all supported model providers you can use for logical grouping. Set using 'codestory config model provider:model' | No | - |
--repo TEXT |
Path to the git repository to operate on. Defaults to current directory. | No | - |
--branch TEXT |
Branch to operate on. Defaults to current branch. | No | - |
--custom-config TEXT |
Path to a custom config file | No | - |
--model TEXT |
LLM model (format: provider:model, e.g., openai:gpt-4) | No | - |
--api-key TEXT |
API key for the LLM provider | No | - |
--api-base TEXT |
Custom API base URL for the LLM provider (optional) | No | - |
--temperature FLOAT |
Temperature for LLM responses (0.0-1.0) | No | - |
--max-tokens TEXT |
Maximum tokens to send per llm request | No | - |
--relevance-filtering |
Whether to filter changes by relevance to your intent ('cst commit' only) | No | - |
--relevance-filter-similarity-threshold FLOAT |
How similar do changes have to be to your intent to be included. Higher means more strict | No | - |
--secret-scanner-aggression [safe|standard|strict|none] |
How aggresively to scan for secrets ('cst commit' only) | No | - |
--fallback-grouping-strategy [all_together|by_file_path|by_file_name|by_file_extension|all_alone] |
Strategy for grouping changes that were not able to be analyzed | No | - |
--chunking-level [none|full_files|all_files] |
Which type of changes should be chunked further into smaller pieces | No | - |
-v, --verbose |
Enable verbose logging output | No | - |
-y, --yes |
Automatically accept all prompts without user confirmation | No | - |
-s, --silent |
Do not output any text to the console, except for prompting acceptance | No | - |
--ask-for-commit-message |
Allow asking you to provide commit messages to optionally override the auto generated ones | No | - |
--display-diff-type [semantic|git] |
Type of diff to display when showing diffs (semantic or git) | No | - |
--custom-language-config TEXT |
Path to custom language configuration JSON file to override built-in language configs | No | - |
--batching-strategy [auto|requests|prompt] |
Strategy for batching LLM requests (auto, requests, prompt) | No | - |
--custom-embedding-model TEXT |
FastEmbed supported text embedding model (will download on first run if not cached) | No | - |
--cluster-strictness FLOAT |
Strictness of clustering logical groups together. (0-1) Higher value = higher threshold of similarity required to group together. | No | - |
--num-retries INTEGER |
How many times to retry calling a model if it fails to return an output (0-10) | No | - |
--no-log-files |
Disable logging to files, only output to console | No | - |
--descriptive-commit-messages |
Whether to use more descriptive and professional commit messages by default | No | - |
--num-recent-commits INTEGER |
Number of recent commit messages to include in the context for summarization (0-50) | No | - |
--run-commit-hooks |
Whether to run git pre-commit and post-commit hooks during 'cst commit' | No | - |
--help |
Show this message and exit. | No | - |
Commands
| Name | Description |
|---|---|
commit |
Commit current changes into small logical... |
fix |
Turn a past commit or range of commits... |
clean |
Fix your entire repository starting from... |
config |
Manage global and local codestory... |
Subcommands
cst commit
Commit current changes into small logical commits. (If you wish to modify existing history, use codestory fix or codestory clean)
Examples: # Commit all changes interactively cst commit
# Commit specific directory with message
cst commit src/ -m "Make 2 commits, one for refactor, one for feature A..."
# Commit changes with an intent filter enabled
cst commit --intent "refactor abc into a class"
Usage
cst commit [OPTIONS] [TARGET]...
Arguments
| Name | Description | Required |
|---|---|---|
[TARGET]... |
Path(s) to file or directory to commit (supports git pathspecs). | No |
Options
| Name | Description | Required | Default |
|---|---|---|---|
-m TEXT |
Context or instructions for the AI to generate the commit message | No | - |
--intent TEXT |
Intent or purpose for the commit, used for relevance filtering. | No | - |
--fail-on-syntax-errors |
Fail the commit if syntax errors are detected in the changes. | No | - |
--staged |
Only commit changes that are already staged. Unstaged changes will be ignored. | No | - |
--help |
Show this message and exit. | No | - |
cst fix
Turn a past commit or range of commits into small logical commits.
Examples: # Fix a specific commit (--start will be parent of def456) cst fix def456
# Fix a range of commits from start to end
cst fix def456 --start abc123
Usage
cst fix [OPTIONS] [COMMIT_HASH]
Arguments
| Name | Description | Required |
|---|---|---|
[COMMIT_HASH] |
Hash of the end commit to split or fix | No |
Options
| Name | Description | Required | Default |
|---|---|---|---|
-m TEXT |
Context or instructions for the AI to generate the commit message | No | - |
--start TEXT |
Hash of the start commit, non inclusive (optional). If not provided, uses end commit's parent. | No | - |
--help |
Show this message and exit. | No | - |
cst clean
Fix your entire repository starting from the latest commit.
Note: This command will stop at the first merge commit encountered. Merge commits cannot be rewritten and will mark the boundary of the clean operation.
Examples: # Clean starting from the latest commit cst clean
# Clean starting from a specific commit with a minimum line count of 5
cst clean abc123 --min-size 5
# Clean while ignoring certain commits
cst clean --ignore def456 --ignore ghi789
# Clean only unpushed commits
cst clean --unpushed
Usage
cst clean [OPTIONS]
Arguments
No arguments available
Options
| Name | Description | Required | Default |
|---|---|---|---|
--ignore TEXT |
Commit hashes or prefixes to ignore. | No | - |
--min-size INTEGER |
Minimum change size (lines) to process. | No | - |
--start TEXT |
Where to start cleaning from (inclusive). Defaults to earliest possible commit. | No | - |
--end TEXT |
Where to end cleaning at. (inclusive). Defaults to HEAD. | No | - |
--unpushed |
Only clean commits that have not been pushed to the upstream branch. | No | - |
--help |
Show this message and exit. | No | - |
cst config
Manage global and local codestory configurations.
Priority order: program arguments > custom config > local config > environment variables > global config
Examples: # Get a configuration value cst config model
# Set a local configuration value
cst config model "gemini/gemini-2.0-flash"
# Set a global configuration value
cst config model "openai/gpt-4" --scope global
# Show all configuration
cst config
# Delete a specific key from local config
cst config model --delete
# Delete all config from global scope
cst config --delete --scope global
# Delete a key from both global and local scopes
cst config model --deleteall
# Delete all config from both scopes
cst config --deleteall
Usage
cst config [OPTIONS] [KEY] [VALUE]
Arguments
| Name | Description | Required |
|---|---|---|
[KEY] |
Configuration key to get or set. | No |
[VALUE] |
Value to set (omit to get current value). | No |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--describe |
Describe available configuration options and exit. | No | - |
--scope [local|global|env] |
Select which scope to modify. Defaults to local for setting/deleting, all for getting. | No | - |
--delete |
Delete configuration. Deletes all config in scope if no key specified, or specific key if provided. | No | - |
--deleteall |
Delete configuration from both global and local scopes. | No | - |
--help |
Show this message and exit. | No | - |