{"id":8635,"library":"sfctl","title":"Azure Service Fabric CLI","description":"sfctl is the Azure Service Fabric command-line interface, a powerful utility for interacting with and managing Service Fabric clusters, applications, and services. It provides a comprehensive set of commands for development, deployment, and operational tasks. The library maintains an active release cadence, with updates often aligning with new Service Fabric runtime versions to ensure compatibility and leverage new features. The current version is 11.2.1.","status":"active","version":"11.2.1","language":"en","source_language":"en","source_url":"https://github.com/Azure/service-fabric-cli","tags":["azure","service-fabric","cli","management","devops","microsoft"],"install":[{"cmd":"pip install sfctl","lang":"bash","label":"Install sfctl"}],"dependencies":[{"reason":"Requires Python 3.8 and above, but less than Python 4.","package":"python","optional":false},{"reason":"Core dependency for CLI parsing; version conflicts with other Azure CLIs can occur.","package":"knack","optional":false}],"imports":[],"quickstart":{"code":"# Install sfctl (if not already installed)\npip install sfctl\n\n# Display help for sfctl commands\nsfctl -h\n\n# Connect to a Service Fabric cluster (example for a local cluster)\n# Replace with your cluster endpoint and certificate details for secure/remote clusters\nsfctl cluster select --endpoint http://localhost:19080\n\n# Check the health of the connected cluster\nsfctl cluster health\n\n# List all applications in the cluster\nsfctl application list","lang":"bash","description":"After installation, use `sfctl -h` to see available commands. The first step is typically to connect to a Service Fabric cluster using `sfctl cluster select`. For secure clusters, you'll need to provide certificate paths (PEM or cert/key pair) and potentially use `--no-verify` for self-signed certificates, though this is not recommended for production environments."},"warnings":[{"fix":"Always use a version of sfctl compatible with your Service Fabric cluster runtime. Refer to the official Service Fabric CLI documentation for the recommended compatibility matrix. Upgrade both sfctl and your cluster if encountering compatibility warnings.","message":"sfctl versions are tightly coupled with Azure Service Fabric runtime versions. Incompatible versions can lead to errors or unexpected behavior. Starting with v7.0.0, sfctl includes a compatibility check, but manual verification is recommended.","severity":"breaking","affected_versions":"All versions, specifically v6.0.0, v7.0.0, v8.0.0, v9.0.0, v10.0.0 introduced updates for specific Service Fabric runtimes."},{"fix":"For self-signed certificates, ensure the certificate is correctly installed in your operating system's trusted root store. For secure clusters, specify the correct `--pem` or `--cert` and `--key` arguments. Avoid `--no-verify` in production.","message":"Connecting to secure Service Fabric clusters, especially those with self-signed certificates, often results in SSL/TLS errors. While `--no-verify` can bypass certificate validation, it is insecure and should be avoided in production.","severity":"gotcha","affected_versions":"All versions when connecting to secure clusters."},{"fix":"Increase the default timeout using the `--timeout` parameter for large application packages. Ensure the client certificate is correctly configured and accessible to sfctl. For large packages, consider using the `--show-progress` option.","message":"Application upload operations (e.g., `sfctl application upload`) can sometimes experience timeouts or '403 Client Error: Client certificate required' even when other commands work. This was particularly noted in older versions.","severity":"breaking","affected_versions":"v7.1.0 and earlier; intermittent in later versions."},{"fix":"Upgrade your Python environment to version 3.8 or higher. Use `pip install sfctl` with a compatible Python 3 interpreter.","message":"Support for Python 2.7 has been deprecated. The library now officially requires Python 3.8 or newer. Using older Python versions will lead to installation and runtime errors.","severity":"deprecated","affected_versions":"< 3.8"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pip install sfctl` completed successfully. Verify Python's script directory (e.g., `~/.local/bin` on Linux/macOS, `Scripts` in Python install dir on Windows) is in your system's PATH environment variable. Reinstall `sfctl` if necessary.","cause":"The `sfctl` executable is not in your system's PATH, or the installation failed.","error":"sfctl: command not found"},{"fix":"Upgrade your Service Fabric cluster, downgrade `sfctl` using `pip install sfctl==<compatible-version>`, or upgrade `sfctl` using `pip install --upgrade sfctl` to match your cluster. Always consult the official compatibility documentation.","cause":"Your installed sfctl version is not compatible with the connected Service Fabric cluster's runtime version.","error":"UserWarning: sfctl has version \"X.Y.Z\" which does not match the cluster version \"A.B.C.D\". See https://learn.microsoft.com/azure/service-fabric/service-fabric-cli#service-fabric-target-runtime for version compatibility. Upgrade to a compatible version for the best experience."},{"fix":"For non-production/testing, add `--no-verify` to your `sfctl cluster select` command (e.g., `sfctl cluster select --endpoint https://... --pem ./client.pem --no-verify`). For production, import the cluster's certificate into your client machine's trusted root certification authorities store, or ensure you are using correctly issued certificates.","cause":"sfctl failed to verify the SSL certificate of the cluster endpoint, often due to self-signed certificates or incorrect certificate configuration.","error":"msrest.exceptions.ClientRequestError: Error occurred in request., ConnectionError: HTTPSConnectionPool(host='yourcluster.region.cloudapp.azure.com', port=19080): Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1018)')))"},{"fix":"Verify the cluster endpoint URL and port are correct. Ensure the cluster is running and accessible from your machine (check network connectivity and firewall rules). For local clusters, confirm `http://localhost:19080` is the correct endpoint.","cause":"The sfctl command could not establish a connection to the Service Fabric cluster, possibly due to incorrect endpoint, network issues, or cluster unavailability/firewall restrictions.","error":"msrest.exceptions.ClientRequestError: Error occurred in request., ConnectionError: HTTPSConnectionPool(host='yourcluster.endpoint', port=19080): Max retries exceeded"},{"fix":"Ensure your `sfctl cluster select` command correctly specifies the client certificate (e.g., `--pem ./client.pem` or `--cert ./client.crt --key ./client.key`) before attempting application upload. Verify the certificate is valid and has permissions to interact with the image store.","cause":"During application upload, the cluster requires a client certificate for authentication, which was either not provided or is invalid.","error":"403 Client Error: Client certificate required for url: https://yourcluster.endpoint:19080/ImageStore/..."}]}