@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

Arguments are parsed with Node's util.parseArgs, so this entry needs Node.js 18.3 or later.

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",...}' }

View source →

§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",...}]' }

View source →

§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",...}}' }

View source →

§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)

View source →

§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,...}]' }

View source →

◈ Interfaces

§interface

AnalyzeCommandOptions

Options for the analyze CLI command.

Properties

§depth?:"basic" | "full" | "deep"Analysis depth level

§exclude?:string[]Glob patterns to exclude

§format?:OutputFormatOutput format (json, table, etc.)

§include?:string[]Glob patterns to include

§path?:stringTarget directory path to analyze

View source →

§interface

CliConfig

CLI configuration.

Properties

§commands:Record<string, Command>Available commands

§name:stringCLI name

§version:stringCLI version

View source →

§interface

Command

CLI command interface.

Properties

§description:stringCommand description

§name:stringCommand name

View source →

§interface

CommandResult

Command execution result.

Properties

§error?:stringError message

§exitCode:numberExit code (0 for success, non-zero for errors)

§output?:stringOutput message

View source →

§interface

ConfigCommandOptions

Options for the config CLI command.

Properties

§format?:OutputFormatOutput format (json, table, etc.)

§path?:stringTarget directory path to scan for configs

§showContents?:booleanInclude file contents in output

§type?:ConfigTypeFilter by specific config type

View source →

§interface

DepsCommandOptions

Options for the deps command.

Properties

§format?:OutputFormatOutput format for the results

§path?:stringPath to the package.json file

§type?:"all" | "production" | "development" | "peer" | "optional"Type of dependencies to list

View source →

§interface

GlobalOptions

Global CLI options available to all commands.

Properties

§help?:booleanShow help information

§json?:booleanOutput as JSON (shorthand for --format json)

§noColor?:booleanDisable colored output

§verbose?:booleanEnable verbose output

§version?:booleanShow version information

View source →

§interface

TreeCommandOptions

Configuration options for the tree command.

Properties

§depth?:numberMaximum directory depth to traverse

§dirsOnly?:booleanShow only directories

§filesOnly?:booleanShow only files

§format?:OutputFormatOutput format (text, json, etc.)

§ignore?:string[]Patterns to exclude from output

§path?:stringRoot path to display tree from

§pattern?:stringGlob pattern to filter entries

§showModified?:booleanDisplay modification dates

§showSize?:booleanDisplay file sizes

View source →

◆ Types

§type

OutputFormat

Output format for CLI commands.

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

View source →

● Variables

§type

analyzeCommandDef

Analyze command definition implementing Command interface.

View source →

§type

configCommandDef

Config command definition implementing Command interface.

View source →

§type

depsCommandDef

Deps command definition implementing Command interface.

View source →

§type

treeCommandDef

Tree command definition implementing Command interface.

View source →