@hyperfrontend/project-scope/cli

CLI Module

The cli module provides a command-line interface for analyzing JavaScript/TypeScript projects. It exposes the library's capabilities through an easy-to-use terminal interface.

Usage

# General usage
project-scope <command> [options]

# Get help
project-scope --help
project-scope <command> --help

Commands

`analyze`

Analyze project structure and technology stack.

# Analyze current directory
project-scope analyze

# Analyze specific project
project-scope analyze ./my-project

# Output as JSON
project-scope analyze --format json

# Deep analysis with all detections
project-scope analyze --depth deep

# Include only specific analyses
project-scope analyze --include frameworks,buildTools

Options:

Option	Description
`--format <text\|json\|yaml>`	Output format (default: text)
`--depth <basic\|full\|deep>`	Analysis depth
`--include <types>`	Analyses to include (comma-separated)
`--exclude <types>`	Analyses to exclude (comma-separated)

`config`

Inspect configuration files in the project.

# List all config files
project-scope config

# Filter by type
project-scope config --type typescript
project-scope config --type eslint,prettier

`deps`

Analyze project dependencies.

# Show dependency summary
project-scope deps

# Show only production dependencies
project-scope deps --type production

# Show dependency graph
project-scope deps --graph

`tree`

Display file tree visualization.

# Show project structure
project-scope tree

# Limit depth
project-scope tree --depth 3

# Show specific directory
project-scope tree src

Global Options

Option	Short	Description
`--help`	`-h`	Show help information
`--version`	`-v`	Show version
`--verbose`		Enable verbose output
`--json`		Output as JSON (shorthand for --format json)
`--no-color`		Disable colored output

Programmatic Usage

The CLI can also be invoked programmatically:

import { run } from '@hyperfrontend/project-scope'

// Analyze current directory
const result = run(['analyze'])

// Analyze with options
const result2 = run(['analyze', './my-project', '--format', 'json'])

// Check result
if (result.exitCode === 0) {
  console.log(result.output)
} else {
  console.error(result.error)
}

Adding Custom Commands

Commands implement the Command interface:

interface Command {
  name: string
  description: string
  execute(args: string[], globalOptions: GlobalOptions): CommandResult
  getHelp(): string
}

Output Formats

Text (default)

Human-readable formatted output with colors and structure.

JSON

Machine-readable JSON output for integration with other tools.

YAML

Human-readable structured output (when available).

API Reference

ƒ Functions

§function

analyzeCommand(options: AnalyzeCommandOptions): CommandResult

Execute analyze command with given options.

Parameters

Name	Type	Description
§options	`AnalyzeCommandOptions`	Configuration for the analyze operation

Returns

CommandResult

Command execution result with exit code and output

Examples

Basic analysis of current directory

const result = analyzeCommand({ depth: 'basic' })
if (result.exitCode === 0) {
  console.log(result.output)
  // => "Project Type: Library\nWorkspace: NX Monorepo\n..."
}

JSON output with filters

const result = analyzeCommand({
  path: './apps/frontend',
  format: 'json',
  depth: 'deep',
  exclude: ['node_modules', 'dist'],
})
// => { exitCode: 0, output: '{"type":"application",...}' }

§function

configCommand(options: ConfigCommandOptions): CommandResult

Execute config command with given options.

Parameters

Name	Type	Description
§options	`ConfigCommandOptions`	Configuration command options

Returns

CommandResult

Command execution result with exit code and output

Examples

Detect all configs in a project

const result = configCommand({ path: './my-project' })
if (result.exitCode === 0) {
  console.log(result.output)
  // => "TypeScript: tsconfig.json\nLinting: eslint.config.js\n..."
}

Filter by type with contents

const result = configCommand({
  path: './my-project',
  type: 'tsconfig',
  showContents: true,
  format: 'json',
})
// => { exitCode: 0, output: '[{"type":"tsconfig","path":"tsconfig.json",...}]' }

§function

depsCommand(options: DepsCommandOptions): CommandResult

Execute deps command with given options.

Parameters

Name	Type	Description
§options	`DepsCommandOptions`	Parsed command options

Returns

CommandResult

Command execution result with exit code and output

Examples

List all dependencies

const result = depsCommand({ path: './my-project' })
if (result.exitCode === 0) {
  console.log(result.output)
  // => "Dependencies\n============\nProduction (3):\n  react  ^18.2.0\n..."
}

Filter to dev dependencies as JSON

const result = depsCommand({
  path: './my-project',
  type: 'development',
  format: 'json',
})
// => { exitCode: 0, output: '{"devDependencies":{"typescript":"^5.0.0",...}}' }

§function

run(args: string[]): CommandResult

Run CLI with given command line arguments.

Parameters

Name	Type	Description
§args	`string[]`	Command line arguments (typically process.argv.slice(2))

Returns

CommandResult

Command result with exit code and optional output/error

Example

Running analysis via CLI

import { run } from '@hyperfrontend/project-scope'

// Analyze current directory
const result = run(['analyze'])

// Analyze specific project with JSON output
const result2 = run(['analyze', './my-project', '--format', 'json'])

// Show dependency tree
const result3 = run(['deps', '--type', 'production'])

process.exit(result.exitCode)

§function

treeCommand(options: TreeCommandOptions): CommandResult

Execute tree command with given options.

Parameters

Name	Type	Description
§options	`TreeCommandOptions`	Configuration for the tree operation

Returns

CommandResult

Command execution result with exit code and output

Examples

Basic tree of current directory

const result = treeCommand({ depth: 2 })
if (result.exitCode === 0) {
  console.log(result.output)
  // => "src/\n├── index.ts\n├── lib/\n│   └── utils.ts\n..."
}

Directories only with metadata

const result = treeCommand({
  path: './project',
  dirsOnly: true,
  showSize: true,
  ignore: ['node_modules', '.git'],
  format: 'json',
})
// => { exitCode: 0, output: '[{"name":"src","isDirectory":true,...}]' }

◈ Interfaces

§interface

AnalyzeCommandOptions

Options for the analyze CLI command.

Properties

§depth?:"basic" | "full" | "deep"—

Analysis depth level

§exclude?:string[]—

Glob patterns to exclude

§format?:OutputFormat—

Output format (json, table, etc.)

§include?:string[]—

Glob patterns to include

§path?:string—

Target directory path to analyze

§interface

CliConfig

CLI configuration.

Properties

§commands:Record<string, Command>—

Available commands

§name:string—

CLI name

§version:string—

CLI version

§interface

Command

CLI command interface.

Properties

§description:string—

Command description

§name:string—

Command name

§interface

CommandResult

Command execution result.

Properties

§error?:string—

Error message

§exitCode:number—

Exit code (0 for success, non-zero for errors)

§output?:string—

Output message

§interface

ConfigCommandOptions

Options for the config CLI command.

Properties

§format?:OutputFormat—

Output format (json, table, etc.)

§path?:string—

Target directory path to scan for configs

§showContents?:boolean—

Include file contents in output

§type?:ConfigType—

Filter by specific config type

§interface

DepsCommandOptions

Options for the deps command.

Properties

§format?:OutputFormat—

Output format for the results

§path?:string—

Path to the package.json file

§type?:"all" | "production" | "development" | "peer" | "optional"—

Type of dependencies to list

§interface

GlobalOptions

Global CLI options available to all commands.

Properties

§help?:boolean—

Show help information

§json?:boolean—

Output as JSON (shorthand for --format json)

§noColor?:boolean—

Disable colored output

§verbose?:boolean—

Enable verbose output

§version?:boolean—

Show version information

§interface

TreeCommandOptions

Configuration options for the tree command.

Properties

§depth?:number—

Maximum directory depth to traverse

§dirsOnly?:boolean—

Show only directories

§filesOnly?:boolean—

Show only files

§format?:OutputFormat—

Output format (text, json, etc.)

§ignore?:string[]—

Patterns to exclude from output

§path?:string—

Root path to display tree from

§pattern?:string—

Glob pattern to filter entries

§showModified?:boolean—

Display modification dates

§showSize?:boolean—

Display file sizes

◆ Types

§type

OutputFormat

Output format for CLI commands.

type OutputFormat = "text" | "json" | "yaml"

● Variables

§type

analyzeCommandDef

Analyze command definition implementing Command interface.

§type

configCommandDef

Config command definition implementing Command interface.

§type

depsCommandDef

Deps command definition implementing Command interface.

§type

treeCommandDef

Tree command definition implementing Command interface.