0
# Command Line Interface
1

2
Command-line interface for Solidity compilation providing standalone compilation capabilities without requiring programmatic API usage.
3

4
## Capabilities
5

6
### CLI Installation and Usage
7

8
When installed globally, solc provides the `solcjs` command-line tool.
9

10
```bash
11
# Global installation
12
npm install -g solc
13

14
# Basic usage
15
solcjs --help
16
```
17

18
### Basic Compilation
19

20
Compile Solidity files to bytecode and ABI.
21

22
```bash
23
# Compile to bytecode
24
solcjs --bin Contract.sol
25

26
# Compile to ABI
27
solcjs --abi Contract.sol
28

29
# Both bytecode and ABI
30
solcjs --bin --abi Contract.sol
31
```
32

33
### Project Structure Support
34

35
Handle complex project layouts with imports and dependencies.
36

37
```bash
38
# Compile with base path and include paths
39
solcjs --bin --include-path node_modules/ --base-path . MainContract.sol
40

41
# Multiple include paths
42
solcjs --bin --include-path ./lib --include-path ./node_modules Contract.sol
43
```
44

45
### Standard JSON Mode
46

47
Use Standard JSON input/output format for advanced compilation.
48

49
```bash
50
# Standard JSON mode (reads from stdin)
51
echo '{"language":"Solidity","sources":{"test.sol":{"content":"contract C {}"}}}' | solcjs --standard-json
52
```
53

54
**Standard JSON Input Example:**
55

56
```json
57
{
58
  "language": "Solidity",
59
  "sources": {
60
    "Contract.sol": {
61
      "content": "contract MyContract { uint public value = 42; }"
62
    }
63
  },
64
  "settings": {
65
    "optimizer": {
66
      "enabled": true,
67
      "runs": 200
68
    },
69
    "outputSelection": {
70
      "*": {
71
        "*": ["abi", "evm.bytecode"]
72
      }
73
    }
74
  }
75
}
76
```
77

78
### Optimization Options
79

80
Control bytecode optimization settings.
81

82
```bash
83
# Enable optimizer
84
solcjs --optimize --bin Contract.sol
85

86
# Set optimizer runs
87
solcjs --optimize --optimize-runs 1000 --bin Contract.sol
88
```
89

90
### Output Management
91

92
Control output format and destination.
93

94
```bash
95
# Specify output directory
96
solcjs --bin --output-dir ./build Contract.sol
97

98
# Pretty-print JSON output
99
solcjs --abi --pretty-json Contract.sol
100

101
# Verbose output
102
solcjs --bin --verbose Contract.sol
103
```
104

105
## CLI Options Reference
106

107
```bash { .api }
108
solcjs [options] <files...>
109

110
Options:
111
  --version                    Show version and exit
112
  --optimize                   Enable bytecode optimizer (default: false)
113
  --optimize-runs <runs>       Number of optimizer runs (default: 200)
114
  --bin                        Output binary bytecode
115
  --abi                        Output ABI specification
116
  --standard-json              Use Standard JSON I/O mode
117
  --base-path <path>           Root of the project source tree
118
  --include-path <paths...>    Extra source directories for imports
119
  -o, --output-dir <dir>       Output directory for compiled files
120
  -p, --pretty-json            Pretty-print JSON output (default: false)
121
  -v, --verbose                Verbose output (default: false)
122
  -h, --help                   Display help information
123
```
124

125
### Path Resolution
126

127
The CLI uses a sophisticated path resolution system:
128

129
- **Base Path**: Root of your source tree (use `.` for current directory)
130
- **Include Paths**: Additional directories containing external code
131
- **Import Resolution**: All imports must be within base path or include paths
132

133
```bash
134
# Correct usage
135
solcjs --bin --base-path . --include-path ./node_modules MyContract.sol
136

137
# Files outside paths will cause errors
138
solcjs --bin --base-path ./src ../external/Library.sol  # Error!
139
```
140

141
### Output Files
142

143
The CLI generates files with specific naming conventions:
144

145
```bash
146
# Input: Contract.sol containing contracts A and B
147
solcjs --bin --abi Contract.sol
148

149
# Generated files:
150
# Contract_sol_A.bin - Bytecode for contract A
151
# Contract_sol_A.abi - ABI for contract A  
152
# Contract_sol_B.bin - Bytecode for contract B
153
# Contract_sol_B.abi - ABI for contract B
154
```
155

156
### Error Handling
157

158
The CLI provides detailed error reporting:
159

160
```bash
161
# Compilation errors
162
solcjs --bin InvalidContract.sol
163
# Exit code: 1
164
# Output includes formatted error messages with line numbers
165

166
# Warning handling (warnings don't cause non-zero exit)
167
solcjs --bin ContractWithWarnings.sol
168
# Exit code: 0
169
# Warnings printed to stdout
170
```
171

172
### Integration Examples
173

174
**Build Script Integration:**
175

176
```bash
177
#!/bin/bash
178
set -e  # Exit on any error
179

180
echo "Compiling contracts..."
181
solcjs --bin --abi --optimize --output-dir ./build *.sol
182

183
echo "Compilation successful!"
184
ls -la ./build/
185
```
186

187
**Package.json Scripts:**
188

189
```json
190
{
191
  "scripts": {
192
    "compile": "solcjs --bin --abi --optimize --output-dir ./build contracts/*.sol",
193
    "compile:dev": "solcjs --bin --abi --verbose contracts/*.sol",
194
    "compile:standard": "cat input.json | solcjs --standard-json --pretty-json"
195
  }
196
}
197
```
198

199
**CI/CD Pipeline:**
200

201
```yaml
202
# GitHub Actions example
203
- name: Compile Solidity contracts
204
  run: |
205
    npm install -g solc
206
    solcjs --bin --abi --optimize \
207
      --base-path . \
208
      --include-path ./node_modules \
209
      --output-dir ./dist \
210
      contracts/*.sol
211
```
212

213
### SMT Solver Integration
214

215
The CLI automatically attempts to use SMT solvers for formal verification:
216

217
```bash
218
# Compile with SMT checking (requires Z3, Eldarica, or cvc5)
219
echo '{
220
  "language": "Solidity",
221
  "sources": {
222
    "test.sol": {
223
      "content": "contract C { function f(uint x) public { assert(x > 0); } }"
224
    }
225
  },
226
  "settings": {
227
    "modelChecker": {
228
      "engine": "chc",
229
      "solvers": ["smtlib2"]
230
    }
231
  }
232
}' | solcjs --standard-json
233
```
234

235
If SMT solvers are not available:
236
```
237
>>> Cannot retry compilation with SMT because there are no SMT solvers available.
238
```
239

240
### Differences from Native solc
241

242
**Important limitations compared to the native `solc` binary:**
243

244
- Not compatible with `eth.compile.solidity()` RPC method
245
- Fewer command-line features than native solc
246
- Uses JavaScript/Emscripten compilation (slower than native)
247
- Cannot be used as a drop-in replacement for native solc
248

249
**When to use solcjs CLI:**
250
- Node.js-based development workflows
251
- Integration with JavaScript tooling
252
- Cross-platform compatibility requirements
253
- When native solc installation is problematic
254

255
**When to use native solc:**
256
- Maximum performance requirements
257
- Full Ethereum client integration
258
- Advanced command-line features
259
- Production deployment pipelines