# dfxmon CLI
[](https://crates.io/crates/dfxmon-cli)
[](https://docs.rs/dfxmon-cli)
[](https://opensource.org/licenses/MIT)
[](https://opensource.org/licenses/Apache-2.0)
**Command-line interface for dfxmon - the universal file watcher and auto-deployment tool for Internet Computer (ICP) projects.**
## Overview
The dfxmon CLI is a client tool that communicates with the dfxmon canister deployed on the Internet Computer. It provides a seamless interface for managing file watching and automatic deployment of your ICP projects.
## Installation
### From crates.io
```bash
cargo install dfxmon-cli
```
### From GitHub Releases
Download the latest binary for your platform from the [GitHub Releases](https://github.com/dfxmon/dfxmon/releases) page.
## Real-World Usage
### Working with an Existing ICP Project
Assuming you have a typical ICP project structure:
```
my-dapp/
├── dfx.json
├── src/
│ ├── backend/
│ │ ├── main.mo # Motoko backend
│ │ └── types.mo
│ ├── frontend/
│ │ ├── src/
│ │ │ ├── App.tsx # React frontend
│ │ │ └── index.ts
│ │ └── package.json
│ └── shared/
│ └── types.did
└── canister_ids.json
```
**Step 1: Register your project with dfxmon**
```bash
cd my-dapp
dfxmon create my-dapp --dfx-json ./dfx.json --auto-deploy
```
**Step 2: Start development with auto-deployment**
```bash
dfxmon watch my-dapp
```
Now when you edit files, dfxmon automatically handles deployments:
- Edit `src/backend/main.mo` → Backend canister redeploys
- Edit `src/frontend/src/App.tsx` → Frontend assets redeploy
- Edit `src/shared/types.did` → Both canisters redeploy
## Commands
### `dfxmon create`
Create a new project in the dfxmon canister.
```bash
dfxmon create <PROJECT_NAME> [OPTIONS]
Options:
--dfx-json <PATH> Path to dfx.json file
--auto-deploy Enable automatic deployment
--debounce-ms <MS> Debounce delay in milliseconds [default: 1000]
```
### `dfxmon watch`
Start watching a project for file changes.
```bash
dfxmon watch <PROJECT_NAME> [OPTIONS]
Options:
--filter <FILTER> Filter files to watch (e.g., "*.rs,*.mo")
```
### `dfxmon deploy`
Manually trigger deployment of a project or specific canister.
```bash
dfxmon deploy <PROJECT_NAME> [OPTIONS]
Options:
--canister <NAME> Deploy specific canister only
--force Force deployment even if no changes detected
```
### `dfxmon status`
Get the status of a project.
```bash
dfxmon status <PROJECT_NAME>
```
### `dfxmon list`
List all projects managed by the dfxmon canister.
```bash
dfxmon list
```
### `dfxmon history`
View deployment history for a project.
```bash
dfxmon history <PROJECT_NAME> [OPTIONS]
Options:
--limit <N> Number of deployments to show [default: 10]
```
### `dfxmon settings`
View or update global settings.
```bash
dfxmon settings [OPTIONS]
Options:
--get Show current settings
--max-deployments <N> Set max concurrent deployments
--debounce <MS> Set default debounce delay
--notifications Enable/disable notifications
--log-level <LEVEL> Set log level (debug, info, warn, error)
```
## Configuration
### Canister ID
The CLI needs to know which dfxmon canister to communicate with. You can specify this in several ways:
1. **Command line flag**:
```bash
dfxmon --canister-id rdmx6-jaaaa-aaaaa-aaadq-cai create my-project
```
2. **Environment variable**:
```bash
export DFXMON_CANISTER_ID=rdmx6-jaaaa-aaaaa-aaadq-cai
dfxmon create my-project
```
3. **Configuration file** (`.dfxmon.toml` in current directory or home):
```toml
canister_id = "rdmx6-jaaaa-aaaaa-aaadq-cai"
network = "local"
```
### Network Configuration
By default, the CLI connects to the local replica (`http://127.0.0.1:4943`). For mainnet or other networks:
```bash
dfxmon --network ic create my-project
```
Or set the network in configuration:
```toml
network = "ic" # or "local", or custom URL
```
## File Watching
When you run `dfxmon watch`, the CLI starts a local file watcher that monitors your project directory for changes. When changes are detected, it notifies the dfxmon canister, which then triggers the appropriate deployment.
### Supported File Types
- **Motoko**: `.mo` files
- **Rust**: `.rs` files
- **Frontend**: `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`, `.scss`
- **Configuration**: `.json`, `.toml`, `.did`
- **Documentation**: `.md`
### Ignored Patterns
The following files and directories are automatically ignored:
- `.dfx/` - DFX build artifacts
- `target/` - Rust build artifacts
- `node_modules/` - Node.js dependencies
- `.git/` - Git repository files
- `dist/`, `build/` - Build output directories
- Temporary files (`*.tmp`, `*.swp`, `*~`)
## Examples
### Multi-Canister Rust Project
Working on a DeFi project with multiple Rust canisters:
```bash
# Project structure:
# defi-dapp/
# ├── src/
# │ ├── token/src/lib.rs # Token canister
# │ ├── exchange/src/lib.rs # Exchange canister
# │ ├── governance/src/lib.rs # Governance canister
# │ └── frontend/src/App.tsx # React frontend
# └── dfx.json
cd defi-dapp
dfxmon create defi-dapp --dfx-json ./dfx.json --auto-deploy
dfxmon watch defi-dapp
# Now edit src/token/src/lib.rs
# → Only the token canister rebuilds and redeploys
# → Other canisters remain untouched
```
### Frontend-Heavy Development
Working on a social media dapp with frequent UI changes:
```bash
# Focus only on frontend changes
dfxmon watch social-dapp --filter "*.tsx,*.css,*.js"
# Edit src/frontend/components/Feed.tsx
# → Frontend assets rebuild and redeploy instantly
# → Backend canisters stay running without interruption
```
### Motoko Backend with TypeScript Frontend
Typical full-stack development workflow:
```bash
# Project: chat-app
dfxmon create chat-app --dfx-json ./dfx.json --auto-deploy
dfxmon watch chat-app
# Terminal 1: dfxmon watching
# Terminal 2: Your editor
# Edit src/backend/main.mo (add new message type)
# → Backend redeploys, Candid interface updates
# → dfxmon detects interface change, triggers frontend rebuild
# Edit src/frontend/src/types.ts (update types)
# → Frontend rebuilds with new types
# → Hot reload in browser shows changes immediately
```
### Production Deployment Monitoring
Using dfxmon to track deployments on mainnet:
```bash
# Connect to mainnet dfxmon canister
export DFXMON_CANISTER_ID="rdmx6-jaaaa-aaaaa-aaadq-cai"
dfxmon --network ic list
# Check production deployment history
dfxmon --network ic history my-production-app --limit 20
# Monitor deployment status
dfxmon --network ic status my-production-app
```
## Troubleshooting
### Common Issues
1. **"Canister ID not provided"**
- Set the canister ID via `--canister-id`, environment variable, or config file
2. **"Failed to connect to replica"**
- Ensure your local replica is running (`dfx start`)
- Check network configuration
3. **"Permission denied"**
- Ensure you have the necessary permissions to interact with the canister
- For local development, make sure you're using the correct identity
4. **"File watching not working"**
- Check that you're in the correct project directory
- Verify the project exists in the dfxmon canister (`dfxmon list`)
### Debug Mode
Enable verbose logging for troubleshooting:
```bash
RUST_LOG=debug dfxmon watch my-project
```
## Contributing
Contributions are welcome! Please see the [main repository](https://github.com/dfxmon/dfxmon) for contribution guidelines.
## License
This project is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## Author
Created by **Dedan Okware** (softengdedan@gmail.com)
## Links
- [Main Repository](https://github.com/dfxmon/dfxmon)
- [Documentation](https://docs.rs/dfxmon-cli)
- [Crates.io](https://crates.io/crates/dfxmon-cli)
- [Issues](https://github.com/dfxmon/dfxmon/issues)