What is sidekick?

Repetitive CLI tasks can be organized in many ways: READMEs, bash scripts, aliases, run configurations, CI/CD pipelines, etc.
But all of these approaches have their drawbacks. Instead, a much better way is to create a CLI that is tailored to your project.

The sidekick CLI generator helps you do just that!

Advantages of a custom sidekick CLI for your project:

  • Documentation of commands inside the CLI - no more outdated documentation as it is linked to the commands
  • Easy language: write commands in Dart instead of complex Bash magic
  • Testable/debuggable
  • Scoped to project: only the commands you need
  • CLI is shared through repo: easy to install and use for new team members

Getting Started - Generating your own sidekick CLI for your project

Creating your own sidekick CLI is easy. Follow these simple steps to get started:

Make sure you have the sidekick CLI generator installed.

dart pub global activate sidekick

Navigate to your project directory and run the following command to initialize a new sidekick CLI:

sidekick init

The CLI generator will guide you through the setup process. You will be prompted to provide some information (e.g. name of your CLI) and that's it!

You can now run your own sidekick CLI by calling it from the command line.

Installing Sidekick CLI Globally and Enabling Tab Completions

To make your Sidekick CLI accessible from anywhere on your system and enable convenient tab completions, run the following command:

<your-cli-name> sidekick install-global

Now restart your terminal or resource your shell profile (e.g. source ~/.bashrc or source ~/.zshrc) and you can run your CLI from anywhere with tab completions.

Available Default Commands and Plugins

The Sidekick CLI comes with a set of default commands to help you get started quickly. Additionally, it supports plugins that can be easily integrated to extend its functionality. Here's a list of some useful default commands and recommended plugins:

Default Commands

These are only some of the commands available in a freshly generated sidekick CLI: deps: Gets dependencies for all packages (including nested packages) format: Formats all Dart files in all packages (including nested packages) sidekick create-command: Creates a template for a new command and adds it to your CLI sidekick plugins create: Create a new sidekick plugin from some templates sidekick plugins install: Install a sidekick plugin to your CLI (from pub.dev/Github/local path)

Enhance your Sidekick CLI with these recommended plugins:

sidekick_vault: Stores secrets within the project’s git repository, encrypted with GPG dockerize_sidekick_plugin: Makes it easy to deploy your flutter web app as a docker container flutterw_sidekick_plugin: Pins Flutter SDK to exact version defined per project phntmxyz_bump_version_sidekick_plugin: Adds command to bump the version of a package

You can find all available sidekick plugins on pub.dev here.

All other packages related to sidekick on pub.dev can be found here.

Install plugins to your cli with <your-cli-name> sidekick plugins install <plugin-name>

Learn More About Sidekick

If you're interested in delving deeper into Sidekick and discovering advanced tips and techniques, consider watching our comprehensive talk:

sidekick_core

This package is used by sidekick CLIs to gain access to those awesome features:

  • Plugin engine
  • Update migrations
  • Templates for new projects and plugins
  • Prebuild commands
    • AnalyzeCommand - Dart analyzes the whole project
    • DartCommand - Calls the Dart SDK embedded in Flutter SDK (default system)
    • DepsCommand - Gets dependencies for all packages
    • FlutterCommand - Call the Flutter SDK associated with the project (default system)
    • BashCommand - Wraps a bash script and converts it to a Dart command
    • SidekickCommand
      • PluginsCommand - To install and create plugins
      • UpdateCommand - To update your CLI to the latest sidekick_core version
      • InstallGlobalCommand - Makes the CLI available globally
      • RecompileCommand - Recompiles the CLI in case it didn't detect changes automatically (path dependencies)

Usage

import 'package:sidekick_core/sidekick_core.dart';

Future<void> main(List<String> args) async {
  final runner = initializeSidekick(mainProjectPath: 'dev/integration_tests/flutter_gallery');
  runner.addCommand(YourCommand());
  runner.addCommand(SidekickCommand());
  return await runner.run(args);
}

License

Copyright 2023 phntm GmbH

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Libraries

sidekick_core
The core library for Sidekick CLIs