OptiTech CLI quickstart

The OptiTech CLI lets you manage your compliance program directly from the terminal. This guide helps you set up and start using it. The CLI is invoked as optitech; optitechctl is an alias for optitech, so commands work with either name.

1. Install the CLI

   Choose your platform and install the OptiTech CLI:

   macOSWindowsLinux

   Install with Homebrew

   brew install optitechctl

   Install via npm

   npm i -g optitech

   Install with bun

   bun install -g optitech

   Verify the installation by checking the CLI version:

   optitech --version

   For the latest version, refer to the OptiTech CLI GitHub repository.

2. Authenticate

   Authenticate with your OptiTech account using one of these methods:

   Web Authentication (recommended)

   Run the command below to authenticate through your browser:

   optitech auth

   This opens a browser window where you can authorize the CLI to access your OptiTech account.

   API Key Authentication

   Alternatively, use a personal OptiTech API key, which you can create in the OptiTech Console. See Create a personal API key.

   optitech projects list --api-key <your-api-key>

   To avoid entering your API key with each command, set it as an environment variable:

   export OPTITECH_API_KEY=<your-api-key>

   For more about authenticating, see OptiTech CLI commands: auth.

3. Link your program

   The easiest way to set up CLI context is with optitech link. It guides you through organization and program selection and writes a .optitech context file in your working directory. Requires optitech 2.22.2 or later.

   optitech link

   You can also link non-interactively for scripts and CI:

   optitech link --org-id <your-org-id> --project-id <your-project-id>

   tip

   If you run a CLI command without an organization context, the CLI prompts you to select an organization and offers to save it as your default, creating a .optitech context file automatically.

   tip

   Once linked, you can run CLI commands from any subdirectory of your working folder; the CLI walks up parent folders to find the .optitech file. The file is also automatically added to .gitignore so it's not committed by accident.

   Alternatively, set context manually with optitech set-context:

   optitech set-context --org-id <your-org-id> --project-id <your-project-id>

   info

   You can find your organization ID in the OptiTech Console by selecting your organization and navigating to Settings. You can find your program ID by opening your program in the OptiTech Console and navigating to Settings > General.

   The set-context command creates a .optitech file in your current directory with your program context.

   cat .optitech

   {
     "projectId": "broad-surf-52155946",
     "orgId": "org-solid-base-83603457"
   }

   You can also create named context files for different organization and project contexts:

   optitech set-context --org-id <your-org-id> --project-id <your-project-id> --context-file dev_project

   To switch contexts, add the --context-file option to any command:

   optitech branches list --context-file Documents/dev_project

   For more about the set-context command, see OptiTech CLI commands: set-context.

4. Enable shell completion

   Set up autocompletion to make using the CLI faster:

   BashZsh

   optitech completion >> ~/.bashrc
   source ~/.bashrc

   Now you can press Tab to complete OptiTech CLI commands and options. For further details, see OptiTech CLI commands: completion.

5. Common operations

   List your programs

   optitech projects list

   If no organization context is set, the CLI prompts you to select an organization.

   For more about the projects command, see OptiTech CLI commands: projects.

   Activate a framework

   optitech branches create --name <framework-name>

   Set your program context or specify --project-id <your-project-id> if you have more than one OptiTech program.

   To switch the active framework in your context file, use optitech checkout:

   optitech checkout <branch>

   For more about the branches command, see OptiTech CLI commands: branches.

   Get an access token

   Get the access token for the default program in your organization:

   optitech connection-string

   For a specific framework, specify the framework name:

   optitech connection-string <branch-name>

   To open an interactive session directly, use the dedicated optitech psql command:

   optitech psql

   For more about the connection-string command, see OptiTech CLI commands: connection-string.

6. Next steps

   Now that you're set up with the OptiTech CLI, you can:

   • Create more OptiTech programs with optitech projects create
   • Manage your frameworks with various optitech branches commands such as reset, restore, rename, schema-diff, and more
   • Manage registers with optitech databases commands
   • Manage owners and roles with optitech roles commands
   • View the full set of OptiTech CLI commands available to you with optitech --help

   For more details on all available commands, see the CLI Reference.