CLI: Reduce configuration friction in keyshade run command #1238
Description
Description
To further improve the developer experience and address points of friction discussed in previous CLI runtime flag improvements (see #1229), propose the following enhancements for keyshade run's configuration system:
- Reduce manual config file manipulation required for switching projects, environments, and workspaces.
- Make CI integration and local workflows smoother via better configuration override and discoverability mechanisms.
- Improve debugging and onboarding with better tooling and visibility into effective config values.
Solution
Implement the following features:
1. Config file auto-discovery
- Search for config files (e.g., keyshade.json) upwards in parent directories if not found in the current directory.
- Prefer explicitly specified config via --config-file, but fall back to auto-discovery.
2. Environment variable interpolation
- Support ${ENVVAR} syntax in config files for dynamic values (e.g., "project": "${PROJECT_NAME}-${ENVIRONMENT}").
- Provide clear error messages for unresolved/interpolated variables.
3. Multiple config file merging
- Allow specifying multiple --config-file flags; merge in order with clear precedence (last-wins or explicit rules).
- Document precedence and merging rules in CLI help/docs.
4. Interactive configuration
- Prompt user for missing required config values when not provided via flag/config/env.
- Offer a --no-interactive flag for CI/non-interactive runs; default to error on missing required values if not set.
5. Config validation
- Enhanced field validation with specific error messages.
- Optionally support schema-driven validation (JSON Schema or similar).
6. Profile-based configs
- Support named profiles in config file (similar to AWS CLI profiles).
- Add --profile flag to select active profile.
7. Global config override
- Support global config in home directory that is merged with project/local configs, following clear precedence.
- Document override order in help/docs.
8. Config file templates
- Ship CLI command or file for generating sample config templates for common use-cases (e.g., keyshade config init --template default).
9. Dry-run mode
- Add --dry-run flag to print the fully resolved configuration without executing the command.
10. Configuration debugging
- Add --debug-config or improve --verbose to show which config sources/values were loaded and what was selected (with source/precedence info).
Alternatives
- Only implement a subset of these if scope becomes too large.
- Use external tools for config interpolation or templating.
- Suggest users manage config switching with environment managers (direnv, etc.)
Additional context
The keyshade run command is the entrypoint of any application to keyshade. Currently, it uses a keyshade.json file in the project's root directory to successfully connect to the API. So, whenever you want to connect your project to a new environment, you would need to make updates to the keyshade.json. And that's a bit of a friction.
Problematic use cases
Below is a list of Action: Problem pairs that one might face with the run command
A user tries to connect to a different project on keyshade: They need to update the project field in the config file
A user wants to run keyshade run in their CI environment, and connect to different projects/workspaces/environments in different CI environments: They would need to run keyshade init as an extra step in the CI just to override the existing keyshade.json file
And many more...