Skip to main content

Installing & Updating

RequirementsRequirements
Review the requirements for your site to run AI Assistant.
InstallationInstallation
Instructions for installing a new copy of AI Assistant.
UpdatingUpdating
Instructions for updating from 1.x to newer versions of AI Assistant 1.x.
PurchasingPurchasing
Trialing, purchasing and troubleshooting license issues.
TroubleshootingTroubleshooting
Common problems encountered when purchasing / upgrading.

​Requirements

AI Assistant 1.x supports Craft 5.x. It meets mostly the same requirements as listed on the Craft Requirements page.

  • Craft 5.0.0+
  • PHP 8.2.0+
  • MySQL 8.0.17+ using InnoDB, MariaDB 10.4.6+, or PostgreSQL 13+
  • 256MB+ of memory allocated to PHP
  • Active/Valid API key(s) for one or more configured providers:
    • OpenAI
    • Google Gemini
    • Anthropic
    • xAI
    • Replicate

​Installation

AI Assistant can be installed one of two ways:

AI Assistant can be installed by running the following set of commands in your favorite CLI app: Recommended

1

Open your Craft project

cd /path/to/project
2

Get AI Assistant

composer require solspace/craft-aiassistant -w
3

Install AI Assistant

Enter the following command:

./craft plugin/install ai-assistant
4

Purchase

If AI Assistant is right for your site, purchase a copy of it through the Plugin Store when you're ready!

​Updating

​Back up your database before continuing...

If the upgrade migration fails at any point, you must be prepared to fully restore your database using the backup you created before initiating the update again. A failed migration may leave the database partially changed or other migrations may have occurred. Downgrading to an earlier version could corrupt the database and make it unrecoverable.

It is essential that you take a complete backup of your database before proceeding with this update!

AI Assistant can be updated one of three ways:

You can use the Craft update command to update AI Assistant. Recommended

1

Open your Craft project

cd /path/to/project
2

Check for Updates

./craft update
3

Perform the Updates

./craft update ai-assistant

​Disable AI Assistant

AI Assistant can be temporarily disabled from the CLI or control panel. The benefit of this is to troubleshoot potential issues and conflicts while preserving your data until a proper fix or change to the site is made.

1

Open your Craft Project

cd /path/to/project
2

Disable AI Assistant

./craft plugin/disable ai-assistant

​Uninstall AI Assistant

Follow the steps below to uninstall AI Assistant from your site.

This action cannot be undone. All of your AI Assistant data be will lost forever, unless you have made a backup.

1

Open your Craft Project

cd /path/to/project
2

Uninstall AI Assistant

./craft plugin/uninstall ai-assistant
3

Remove Dependencies

Do not remove a plugin package with Composer before uninstalling it from the control panel or with Craft's CLI.

composer remove solspace/craft-aiassistant

​Purchasing

Craft allows you to trial third-party plugins to see if they're right for your needs. We recommend trying any commercial plugin first before buying it. You can trial any plugin or Craft CMS itself by running your site from any domain that Craft does not consider to be a public domain.

​Understanding versions and composer update

  • For example, under the "require" area, change "solspace/craft-aiassistant": "1.0.2", to "solspace/craft-aiassistant": "1.1.3",.
  • You can also use ~ and ^ to somewhat automate your updating process.
    • 1.0.0 - means exactly & only this version
    • ~1.0.0 - means this version & any patch release (up to 1.0.99̅)
    • ^1.0.0 - means this version & any minor release (up to 1.99̅.99̅)
      • Specifying "solspace/craft-aiassistant": "^1.0.0", for example, would always get you the latest version of AI Assistant 1.x (e.g. 1.1.9), but never the next major version of AI Assistant like 2.x.

Your final composer.json file might have something like this:

"require": {
    "craftcms/cms": "^5.0.0",
    "vlucas/phpdotenv": "^5.4.0",
    "solspace/craft-aiassistant": "^1.0.0",
    "solspace/craft-freeform": "^5.0.0",
},
Getting Latest Unreleased Version...

Sometimes you need to update your site to use the latest unreleased changes in the AI Assistant repository. This could be in the main branch or a temporary fix/feat branch, e.g. v1 or feat/SFT-123.


To access the latest unreleased version of AI Assistant (v1), you would set the version in your composer.json file to just v1.x-dev and run composer update after. Your final composer.json file might have something like this:


"require": {
    "craftcms/cms": "^5.0.0",
    "vlucas/phpdotenv": "^5.4.0",
    "solspace/craft-aiassistant": "v1.x-dev",
    "solspace/craft-freeform": "^5.0.0",
},

To access an unreleased version from a different branch (e.g. feat/SFT-123), you would prefix the branch with dev- + the exact branch path/name. We also recommend that you run those changes as a "dummy" next version number and append a beta version. For example, if the current released version of AI Assistant is 1.3.4 and there are new unreleased changes in the feat/SFT-123 branch you want to grab, go up 1 patch version number + -beta.1. In this case, we would assume 1.3.5 was the next version, so we'd create the version number: 1.3.5-beta.1. Altogether, we'd be specifying: dev-feat/SFT-123 as 1.3.5-beta.1.


Your final composer.json file might have something like this:


"require": {
    "craftcms/cms": "^5.0.0",
    "vlucas/phpdotenv": "^5.4.0",
    "solspace/craft-aiassistant": "dev-feat/SFT-123 as 1.3.5-beta.1",
    "solspace/craft-freeform": "^5.0.0",
},

If there are more unreleased changes to the repo in the future, you could change -beta.1 to -beta.2 and so on. For example, dev-feat/SFT-123 as 1.3.5-beta.2.

​Troubleshooting

Third-party plugin licenses are managed and validated entirely by Craft. Some issues may require that you contact the Craft Team directly if issues persist. The following troubleshooting tips account for the most common issues we've seen our customers report to us:

Error: 'This license is tied to another Craft install'

If you receive the error This license is tied to another Craft install. Visit id.craftcms.com to resolve. it indicates that the license is tied to another install of Craft CMS. This is likely because either you purchased this under a different domain or subdomain, or something glitched in the process of purchasing the license. Regardless of what happened here, this can likely be resolved by:

  1. Visit your Craft Console account.
  2. Under Licenses → Plugins, look for the AI Assistant (or affected plugin) license in the list and confirm it's tied to the correct Craft CMS license. If not, click into the license (e.g. CRZ6) and click on the Detach from this Craft license button. This will release it from being attached to the wrong or orphaned Craft CMS license and allow you to enter it into the Craft install you're using.

If you are moving an existing site to a new non-public domain from a different local hostname, you will need to clear your data caches from the Clear Caches tool on the Settings page before Craft realizes that the hostname has changed.

Error: 'This license isn't allowed to run version X.X.X.'

If you receive the error This license isn't allowed to run version X.X.X., it indicates that you're using a version of the plugin that your license isn't eligible for, which in almost all cases would be a plugin license that expired/finished the 1-year term since the initial purchase. According to Craft's policy (out of Solspace's control), once the plugin license has expired, the current version you have installed is the maximum version you can have. The rationale behind this (according to Craft) is that if, for example, you were using AI Assistant 1.6.1 at the time of expiry, but 1.7.4 was available to you just before the license expiry date, if that 1.7.4 version was available to you indefinitely, one might update to that version months or years later and experience issues while upgrading, which could generate issues and support requests to the developer beyond that initial 1 year term. This is a fair statement and concern on Craft's part, in our opinion. Craft does send out 30-day notices reminding customers of plugin licenses nearing expiry, so it would be wise to consider squeezing in your final update(s) earlier in that 30-day window if you do not wish to renew your license for future updates beyond the initial 1-year term.

When a license expires, you can keep using the version that's currently installed. However, you won't be able to update it to newer versions until you've renewed the license.

As for how this happened in the first place, Craft's CP updater and their recommended built-in update command feature will make sure that you never update to a plugin version you don't have access to. However, if you used Composer to update, it bypasses all of Craft's license validation and you can get yourself into the situation where you now have a version that your license shouldn't have access to, which then generates the error inside the Craft CP. The only way to resolve this would be reverting back to the previous version (which is not always recommended, as it's possible plugin update migration(s) could have taken place, and reverting could break your install), or renew your license. Please feel free to reach out to us for further clarification and assistance if you're in a bind with this, and we'll do the best we can to help.

Plugin shows it's 'Missing'

If you have a plugin that shows as Missing, this is because you don't have the plugin installed and/or the plugin files are not in the Craft vendor folder, BUT you have a valid purchased Craft 3 license for the plugin tied to that Craft install. Depending on your scenario, you likely either have the issue of wanting the plugin to be available or not wanting it to show up there.

If you purchased the plugin and are expecting it to show up for installation, what likely happened is that Craft or your server environment glitched and didn't correctly add the plugin dependency (files) to your Craft site's vendor folder (but knows that you have a valid purchase of it). If this is the case, you'll need to follow the Installation Instructions documentation above to install the plugin.

If the above is not the case for you, and you don't want this license showing up on your Craft site, this can likely be resolved by:

  1. Visit your Craft Console account.
  2. Under Licenses → Plugins, look for the AI Assistant (or affected plugin) license in the list and confirm it's tied to the correct Craft CMS license. If not, click into the license (e.g. CRZ6) and click on the Detach from this Craft license button. This will release it from being attached to the wrong or orphaned Craft CMS license, and later use it on the correct/different Craft install.
Page Feedback