A unified command-line interface for interacting with the development ecosystem.
CLI provides a consistent terminal interface for common development, project, infrastructure, and operational workflows.
Rather than requiring developers or automation to understand the implementation details of every repository, CLI exposes stable commands that coordinate capabilities across the ecosystem.
Its purpose is to provide one predictable entry point for humans, scripts, CI systems, and eventually autonomous agents.
As an ecosystem grows, operational knowledge becomes distributed.
Different repositories expose different scripts.
Different tools use different commands.
Common workflows require remembering implementation details.
A�[118;1:3uutomation becomes tightly coupled to repository structure.
CLI exists to provide a stable interface above those systems.
Instead of remembering:
```text package manager commands repository-specific scripts deployment commands generation scripts validation commands infrastructure utilities ```
developers interact through a consistent command surface.
```text paszed ```
The exact command namespace and interface will evolve as concrete requirements emerge.
The CLI should be:
- Predictable
- Composable
- Scriptable
- Discoverable
- Fast
- Safe
- Automation-friendly
- Independent of implementation details
Commands should represent meaningful operations rather than thin aliases for arbitrary shell commands.
CLI sits above reusable ecosystem capabilities.
```text Developer │ Automation │ Agent │ ▼ CLI │ ├── Bootstrapper ├── Engineering ├── Identity ├── Event Platform ├── Observability ├── Testkit └── Other Capabilities ```
The CLI coordinates these systems without owning their underlying domain logic.
CLI may include commands for:
- Project creation
- Project initialization
- Repository validation
- Development environment checks
- Dependency inspection
- Testing
- Formatting
- Linting
- Type checking
- Builds
- Releases
- Configuration
- Diagnostics
- Environment inspection
- Code generation
- Content operations
- Search indexing
- Infrastructure utilities
- Authentication
- Ecosystem introspection
```text cli/ ├── commands/ ├── config/ ├── core/ ├── errors/ ├── output/ ├── prompts/ ├── runtime/ ├── services/ ├── utils/ └── main ```
The structure will evolve alongside the command surface.
Commands should remain thin.
A command is responsible for:
- Parsing input
- Validating arguments
- Invoking the appropriate capability
- Presenting the result
- Returning a meaningful exit code
Domain logic should live in the repository or package that owns the capability.
Conceptually:
```text Command │ ▼ Input Validation │ ▼ Capability │ ▼ Result │ ▼ Output Formatter ```
This keeps CLI behavior easy to test and prevents the command layer from becoming a second application architecture.
Commands should follow consistent conventions.
Conceptually:
```text paszed create paszed check paszed test paszed build paszed doctor paszed search paszed release ```
Subcommands can expose more specialized operations.
```text paszed project create paszed project check
paszed search build paszed search inspect
paszed env doctor paszed env info ```
The final command hierarchy should emerge from real usage rather than being designed exhaustively in advance.
The CLI should explain itself.
Every command should provide useful help output.
```text paszed --help paszed project --help paszed project create --help ```
Users should not need external documentation to discover basic functionality.
Errors should provide enough context to understand:
- What failed
- Why it failed
- What can be done next
CLI output should be designed for both humans and machines.
Human-readable output should be concise and structured.
```text ✓ Configuration valid ✓ Tests passed ✓ Build completed ```
Machine-readable output may be exposed when appropriate.
```text paszed check --json ```
This enables the same command surface to support:
- Developers
- Shell scripts
- CI pipelines
- External tooling
- AI agents
Commands should return meaningful exit codes.
```text 0 Success 1 General failure 2 Invalid input
More specialized codes may be introduced where they provide concrete value.
Scripts and agents should be able to determine command success without parsing human-readable output.
---
## Configuration
Configuration should follow predictable precedence.
Conceptually:
\```text
Command Arguments
│
▼
Environment Variables
│
▼
Project Configuration
│
▼
User Configuration
│
▼
Defaults
\```
Configuration behavior should remain explicit and inspectable.
Hidden state should be minimized.
---
## Safety
Commands capable of destructive operations should make that behavior explicit.
Potentially destructive commands may require:
- Confirmation
- Explicit flags
- Dry-run support
- Environment validation
For example:
\```text
paszed deploy --dry-run
paszed clean --confirm
\```
Automation should be able to opt into explicit non-interactive behavior.
Safety mechanisms should not make automation impossible.
---
## Automation
CLI should be designed as an automation boundary from the beginning.
A command should behave consistently whether invoked by:
- A developer
- A shell script
- CI
- Another program
- An AI agent
This means avoiding unnecessary interactive behavior and providing structured alternatives when interaction is required.
Conceptually:
\```text
Human ───────┐
│
CI ──────────┤
▼
Script ──── CLI ──── Ecosystem
▲
Agent ───────┘
\```
---
## Agent Interface
A long-term objective is for autonomous agents to operate the ecosystem through the same stable interfaces available to developers.
An agent should not need to understand internal repository implementation details to perform common operations.
For example, an agent could eventually:
\```text
create project
│
▼
configure capabilities
│
▼
validate environment
│
▼
run tests
│
▼
build project
│
▼
inspect diagnostics
\```
CLI becomes one of the primary execution boundaries between AI systems and development infrastructure.
---
## CLI vs Bootstrapper
CLI and Bootstrapper have distinct responsibilities.
\```text
CLI
│
├── Command interface
├── User interaction
├── Automation interface
└── Capability orchestration
Bootstrapper
│
├── Project scaffolding
├── Template composition
├── Initial configuration
└── Environment initialization
\```
CLI may invoke Bootstrapper.
Bootstrapper should not depend on CLI for its core functionality.
This allows project-generation capabilities to remain reusable outside the command-line interface.
---
## CLI vs Shell Scripts
Shell scripts remain useful for small, local tasks.
CLI exists for workflows that require a stable, reusable interface.
A useful boundary is:
\```text
Local implementation detail
│
▼
Script
Reusable ecosystem operation
│
▼
CLI
\```
Not every script needs to become a command.
Commands should exist when an operation becomes part of the supported development interface.
---
## Observability
CLI operations should expose useful diagnostics.
Where appropriate, commands may provide:
- Execution duration
- Structured errors
- Debug output
- Trace identifiers
- Operation metadata
- Verbose logging
For example:
\```text
paszed check --verbose
paszed build --debug
\```
CLI should integrate with shared observability infrastructure rather than inventing an independent telemetry model.
---
## Testing
Command behavior should be testable without invoking the entire executable for every test.
The architecture should allow command handlers to receive controlled inputs and dependencies.
Testkit may provide shared utilities for:
- Command execution
- Output capture
- Environment isolation
- Filesystem fixtures
- Exit-code assertions
- Prompt simulation
End-to-end tests can verify the compiled CLI separately.
---
## Boundaries
CLI owns:
- Command definitions
- Argument parsing
- Command routing
- Terminal interaction
- Output formatting
- CLI configuration
- Exit behavior
- Capability orchestration
CLI does **not** own:
- Project-generation logic
- Authentication semantics
- Event semantics
- Search algorithms
- Observability infrastructure
- Testing infrastructure
- Application business logic
Those responsibilities belong to their respective systems.
---
## Ecosystem
CLI provides a command surface across the broader ecosystem.
It may integrate with:
- **Bootstrapper** — Project creation and initialization
- **Engineering** — Repository standards and validation
- **Identity** — Authentication and credential workflows
- **Event Platform** — Event inspection and development utilities
- **Observability** — Diagnostics and telemetry
- **Testkit** — CLI testing infrastructure
- **Content Engine** — Content processing operations
- **Search** — Index generation and inspection
- **Data Platform** — Connector and synchronization operations
- **Trust Platform** — Policy and moderation tooling
- **Agent Network** — Agent execution and orchestration
The CLI should expose these capabilities without duplicating their implementations.
---
## Long-Term Vision
The long-term goal is to provide a coherent control surface for the entire development ecosystem.
Creating a project, configuring capabilities, validating architecture, running tests, inspecting infrastructure, generating artifacts, and operating development workflows should all be accessible through predictable commands.
This becomes increasingly important as automation grows.
Humans should have a clean terminal interface.
CI should have deterministic commands.
Scripts should have stable contracts.
Agents should have structured operations they can safely execute.
The CLI becomes the operational interface connecting all of them.
---
## Status
CLI is in early development.
Commands will be introduced as real workflows emerge across the ecosystem rather than creating a large speculative command surface upfront.
---
## License
Licensed under the MIT License.