diff --git a/README.md b/README.md
index e6b5fe0..49fbd31 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,11 @@
 # DeployHQ API library and CLI client
 
+> **DEPRECATED:** The CLI in this gem is deprecated and will be removed in a future release.
+> Please use the new [DeployHQ CLI](https://github.com/deployhq/deployhq-cli) instead,
+> which offers more features, fewer dependencies, and first-class support for AI-assisted workflows.
+>
+> The Ruby API library (`Deploy::Resource`, etc.) remains available for programmatic use.
+
 ## Installation
 
 You'll need Ruby installed on your system. We've tested on `2.7.8` and later.
@@ -20,53 +26,22 @@ username and API key are user specific.
 
 ## Usage
 
-### CLI client
+### CLI (deprecated)
 
-The CLI client is still experimental and requires some work. Currently it has
-the ability to list all of the servers on a project, and make a new deployment
-to the most recent revison of a repository.
+The CLI bundled in this gem is deprecated. Please use the
+[new DeployHQ CLI](https://github.com/deployhq/deployhq-cli) instead.
 
-#### List servers
-```
-$ deployhq servers
-Ungrouped Servers
-              Name : localhost
-              Type : SSH/SFTP
-              Path : /home/dan/testing/deploytest
-            Branch : master
-  Current Revision : 70039facbbfb014e4e57ff0bea2c7f6ec5e48e0a
-          Hostname : localhost:22
-```
+### Ruby API
 
-#### Make a deployment
-```
-$ deployhq deploy
-1. localhost (branch: master) (currently: 70039facbbfb014e4e57ff0bea2c7f6ec5e48e0a)
-2. List Server Details
-Please choose a server or group to deploy to:
-1
-Waiting for deployment capacity......
-  Running pre-deployment checks...
-  Checking access to repository
-  Checking start and revisions are valid
-  Checking connection to server localhost
-  Beginning deployment from 70039facbbfb014e4e57ff0bea2c7f6ec5e48e0a to 70039facbbfb014e4e57ff0bea2c7f6ec5e48e0a
-  Deployment started by Dan Wentworth
-  Calculating changes required for deployment
-[ localhost ] Connecting to server at localhost:22
-[ localhost ] Connected to SFTP/SSH server at localhost:22
-[ localhost ] 0 file(s) are no longer required and will be removed
-[ localhost ] 0 file(s) have been changed and will be uploaded
-[ localhost ] 0 config file(s) need to be uploaded
-[ localhost ] Disconnected from SFTP/SSH server
-  Deployment complete!
-  Delivered notification to git-http-test-2 in test-repositories project.
-```
+The `Deploy::Resource` API library remains available for programmatic access
+to the DeployHQ platform. See the source under `lib/deploy/` for available
+resources (Project, Deployment, Server, ServerGroup, etc.).
 
 ## Development
 
-The CLI client in particular is a bit experimental, and not yet finished. Any
-pull-requests to improve it would be greatly welcomed.
+CLI improvements and new features should be directed to the
+[deployhq-cli](https://github.com/deployhq/deployhq-cli) repository.
+This gem will continue to receive maintenance updates for the Ruby API library.
 
 ## Release
 
diff --git a/deployhq.gemspec b/deployhq.gemspec
index 5e54a9c..5296a29 100644
--- a/deployhq.gemspec
+++ b/deployhq.gemspec
@@ -8,8 +8,10 @@ Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.required_ruby_version = '>= 2.7'
   s.licenses = ['MIT']
-  s.summary = 'API and CLI client for the DeployHQ'
-  s.description = 'API and CLI client for the DeployHQ deployment platform. Provides the deployhq executable.'
+  s.summary = 'API and CLI client for the DeployHQ (CLI deprecated)'
+  s.description = 'API and CLI client for the DeployHQ deployment platform. ' \
+                  'NOTE: The CLI is deprecated. ' \
+                  'Please use https://github.com/deployhq/deployhq-cli instead.'
   s.files = Dir.glob('{lib,bin}/**/*')
   s.require_paths = ['lib']
   s.bindir = 'bin'
@@ -22,4 +24,8 @@ Gem::Specification.new do |s|
   s.authors = ['DeployHQ Team']
   s.email = ['support@deployhq.com']
   s.homepage = 'https://github.com/deployhq/deployhq-lib'
+  s.post_install_message = <<~MSG
+    WARNING: The DeployHQ CLI bundled in this gem is deprecated.
+    Please migrate to the new CLI: https://github.com/deployhq/deployhq-cli
+  MSG
 end
diff --git a/lib/deploy/cli.rb b/lib/deploy/cli.rb
index eead0b5..1895887 100644
--- a/lib/deploy/cli.rb
+++ b/lib/deploy/cli.rb
@@ -22,7 +22,19 @@ class CLI
 
     class << self
 
+      DEPRECATION_NOTICE = <<~MSG
+        \e[33m╔══════════════════════════════════════════════════════════════════╗
+        ║  DEPRECATED: This CLI is deprecated and will be removed in a    ║
+        ║  future release. Please migrate to the new DeployHQ CLI:       ║
+        ║                                                                ║
+        ║    https://github.com/deployhq/deployhq-cli                    ║
+        ║                                                                ║
+        ║  More features, fewer dependencies, and built for the AI era.  ║
+        ╚══════════════════════════════════════════════════════════════════╝\e[0m
+      MSG
+
       def invoke(args)
+        warn DEPRECATION_NOTICE
         @options = OptionsStruct.new
 
         parser = OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
diff --git a/lib/deploy/cli/deployment_progress_output.rb b/lib/deploy/cli/deployment_progress_output.rb
index a7caacd..ea31b07 100644
--- a/lib/deploy/cli/deployment_progress_output.rb
+++ b/lib/deploy/cli/deployment_progress_output.rb
@@ -14,9 +14,9 @@ class DeploymentProgressOutput
       def initialize(deployment)
         @deployment = deployment
 
-        @step_index = @deployment.steps.each_with_object({}) { |s, hsh| hsh[s.identifier] = s }
-        @server_tags = @deployment.servers.each_with_object({}) do |s, hsh|
-          hsh[s.id] = "\e[#{SERVER_TAG_COLOURS.next};1m[#{s.name}]\e[0m "
+        @step_index = @deployment.steps.to_h { |s| [s.identifier, s] }
+        @server_tags = @deployment.servers.to_h do |s|
+          [s.id, "\e[#{SERVER_TAG_COLOURS.next};1m[#{s.name}]\e[0m "]
         end
       end