CLI Reference¶
Apiary includes a comprehensive command-line interface (CLI) for common maintenance and development tasks. All commands are accessed through a single apiary entry point with various subcommands.
Overview¶
The CLI is built with Click and provides a consistent interface for:
- Starting the development server
- Initializing and validating configuration
- Backing up configuration and custom code
- Testing application before deployment
- Cleaning up generated files
- Managing the Docker container (
docker up,docker down,docker restart)
Installation¶
The CLI is automatically installed when you install Apiary:
Usage¶
All commands follow this pattern:
Getting Help¶
# Show all available commands
uv run apiary --help
# Show help for a specific command
uv run apiary serve --help
uv run apiary init --help
# Show version
uv run apiary --version
Commands¶
apiary¶
Apiary - Personal API service maintenance CLI.
Usage:
Options:
backup¶
Backup configuration files and optionally custom code.
Creates a timestamped backup of configuration files in backups/YYYYMMDD/. Use --include-custom to also backup services_custom/ and routers_custom/.
Usage:
Options:
--config-dir TEXT Configuration directory to backup [default: config]
--backup-dir TEXT Backup directory path [default: backups]
--include-custom Also backup services_custom/ and routers_custom/
directories
--help Show this message and exit.
clean¶
Clean up generated files and caches.
Usage:
Options:
docker¶
Manage the application Docker container via docker compose.
Usage:
Options:
down¶
Stop and remove the application container.
Usage:
Options:
restart¶
Restart the running application container.
Use this after editing files in the mounted config/ or services/ volumes so the application picks up the changes.
Usage:
Options:
up¶
Start the application container in the background.
Pass --build to rebuild the image first (required after code changes outside of the mounted config/ and services/ volumes).
Usage:
Options:
init¶
Initialize configuration files and optional custom code directories.
Creates config from templates and, by default, services_custom/ and routers_custom/. Custom directories are gitignored so your code is never overwritten when you pull updates. Put custom services and routers there.
Usage:
Options:
-f, --force Overwrite existing config files
--custom-dirs / --no-custom-dirs
Create services_custom/ and routers_custom/
for update-safe custom code [default:
custom-dirs]
--help Show this message and exit.
serve¶
Start the API server.
Usage:
Options:
-h, --host TEXT Bind host [default: 127.0.0.1]
-p, --port INTEGER Bind port [default: 8000]
--reload Enable auto-reload
--help Show this message and exit.
test¶
Test application configuration and imports.
Validates configuration files and tests that the application can be imported and initialized successfully. Use this before deploying updates to catch errors early.
Usage:
Options:
--config-dir TEXT Configuration directory path [default: config]
--skip-import Skip application import test (only validate config)
--help Show this message and exit.
validate-config¶
Validate API key configuration files.
Usage:
Options:
Exit Codes¶
All commands return standard exit codes:
0- Success- Non-zero - Failure
This makes them suitable for use in scripts and CI/CD pipelines.
Output Formatting¶
The CLI uses colored output for better readability:
- 🔧 Blue - Command running
- ✅ Green - Success
- ❌ Red - Failure
- 📊 - Informational messages