Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

19.4 KB
Raw Blame
import { Array as Arr, Data, Effect, HashSet, Layer, Option } from 'effect';
import { Command, HelpDoc, ValidationError } from '@effect/cli';
import {
  hasCommandName,
  listSubcommandNames,
  preflightParse,
  type AnyCommandDescriptor,
} from './command-introspection';
import { $defaultCmd } from './$default.cmd';
import { getVersion } from 'src/effects/version';
import { versionCmd } from './version.cmd';
import { upgradeCmd } from './upgrade.cmd';
import { whoamiCmd } from './whoami.cmd';
import { loginCmd } from './login.cmd';
import { signupCmd } from './signup.cmd';
import { setupCmd } from './setup.cmd';
import { listenCmd } from './listen.cmd';
import { logoutCmd } from './logout.cmd';
import { runCmd } from './run.cmd';
import { proxyCmd } from './proxy.cmd';
import { artifactsCmd } from './artifacts.cmd';
import { installCmd } from './install.cmd';
import { localToolsCmd } from './local-tools/local-tools.cmd';
import { generateCmd } from './generate/generate.cmd';
import { buildDevCommand, devSubcommands } from './dev.cmd';
import {
  runParallelToolsExecuteFromArgv,
  showToolsExecuteInputHelp,
  TOOLS_EXECUTE_VALUE_OPTIONS,
} from './tools/commands/tools.execute.cmd';
import {
  printRootHelp,
  matchSubcommandHelp,
  parseHelpLevel,
  printSubcommandHelp,
} from './root-help';
import { rootToolsCmd$Search } from './tools/commands/tools.search.cmd';
import { rootToolsCmd$Execute } from './tools/commands/tools.execute.cmd';
import { rootToolsCmd } from './tools/tools.cmd';
import { rootTriggersCmd } from './triggers/root-triggers.cmd';
import { rootConnectedAccountsCmd$Link } from './connected-accounts/commands/connected-accounts.link.cmd';
import { orgsCmd } from './orgs/orgs.cmd';
import { configCmd } from './config/config.cmd';
import { rootConnectionsCmd } from './connections/connections.cmd';
import { agentCmd } from './agent/agent.cmd';
import { renderCommandHintGraph } from 'src/services/command-hints';
import { cliDebugFlagsLayer, type CliDebugFlagOverrides } from 'src/services/runtime-flags';
import { cliRunIdLayer } from 'src/services/runtime-cli-context';
import { ComposioCliUserConfig } from 'src/services/cli-user-config';
import { ComposioUserContext } from 'src/services/user-context';
import { TerminalUI } from 'src/services/terminal-ui';
import { detectMasterFromHost } from 'src/services/master-detector';
import {
  formatResolveCommandProjectError,
  resolveCommandProject,
} from 'src/services/command-project';
import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
import { installSkill, type SkillInstallTarget } from 'src/effects/install-skill';
import { experimental, type CommandVisibility, tagged, visibleValues } from './feature-tags';
import { withBackgroundUpdateCheck } from './background-update-check';
import { configureCliAnalyticsReleaseVersion } from 'src/analytics/events';

const ROOT_COMMANDS = [
  tagged(versionCmd),
  tagged(upgradeCmd),
  tagged(whoamiCmd),
  tagged(loginCmd),
  tagged(signupCmd),
  tagged(setupCmd),
  tagged(agentCmd),
  experimental(CLI_EXPERIMENTAL_FEATURES.LISTEN, listenCmd),
  tagged(logoutCmd),
  tagged(runCmd),
  tagged(proxyCmd),
  tagged(artifactsCmd),
  tagged(installCmd),
  experimental(CLI_EXPERIMENTAL_FEATURES.LOCAL_TOOLS, localToolsCmd),
  tagged(rootToolsCmd),
  tagged(rootTriggersCmd),
  tagged(rootToolsCmd$Search),
  tagged(rootConnectedAccountsCmd$Link),
  tagged(rootToolsCmd$Execute),
  tagged(rootConnectionsCmd),
  tagged(generateCmd),
  tagged(orgsCmd),
  tagged(configCmd),
];

const getVisibleRootCommands = (visibility: CommandVisibility) => {
  type RootCommand = (typeof ROOT_COMMANDS)[number]['value'];
  return Arr.append(
    visibleValues<RootCommand>(ROOT_COMMANDS, visibility),
    buildDevCommand(visibility)
  );
};

export const buildRootCommand = (visibility: CommandVisibility) =>
  $defaultCmd.pipe(Command.withSubcommands(getVisibleRootCommands(visibility)));

const ROOT_INSTALL_SKILL_FLAGS = HashSet.make('--install-skill', '--instal-skill');
const SKILL_INSTALL_TARGETS: ReadonlyArray<SkillInstallTarget> = ['claude', 'codex', 'openclaw'];

class RootCommandError extends Data.TaggedError('commands/RootCommandError')<{
  readonly message: string;
}> {}

type RootInstallSkillRequest = {
  readonly skillName?: string;
  readonly target: SkillInstallTarget;
};

const isSkillInstallTarget = (value: string): value is SkillInstallTarget =>
  SKILL_INSTALL_TARGETS.some(target => target === value);

const rootCommandError = (message: string) => Effect.fail(new RootCommandError({ message }));

const findRootInstallSkillValues = (
  args: ReadonlyArray<string>
): Option.Option<ReadonlyArray<string>> =>
  Arr.matchLeft(args, {
    onEmpty: Option.none,
    onNonEmpty: (token, tail) => {
      if (HashSet.has(ROOT_INSTALL_SKILL_FLAGS, token)) {
        return Option.some(Arr.takeWhile(tail, value => !value.startsWith('-')));
      }
      if (token === '--log-level') {
        return findRootInstallSkillValues(Arr.drop(tail, 1));
      }
      if (token.startsWith('--log-level=') || token.startsWith('-')) {
        return findRootInstallSkillValues(tail);
      }
      return Option.none();
    },
  });

const parseRootInstallSkillValues = (
  rawValues: ReadonlyArray<string>
): Effect.Effect<RootInstallSkillRequest, RootCommandError> =>
  Arr.match(rawValues, {
    onEmpty: () =>
      rootCommandError(
        'Missing target for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>'
      ),
    onNonEmpty: ([first, second, ...rest]) => {
      if (rest.length > 0) {
        return rootCommandError(
          'Too many arguments for --install-skill. Usage: composio --install-skill [skill-name] <claude|codex|openclaw>'
        );
      }
      const target = second ?? first;
      if (!isSkillInstallTarget(target)) {
        return rootCommandError(
          'Invalid target for --install-skill. Expected one of: claude, codex, openclaw.'
        );
      }
      return Effect.succeed(second === undefined ? { target } : { skillName: first, target });
    },
  });

export const parseRootInstallSkillRequest = (
  argv: ReadonlyArray<string>
): Effect.Effect<Option.Option<RootInstallSkillRequest>, RootCommandError> =>
  Option.match(findRootInstallSkillValues(Arr.drop(argv, 2)), {
    onNone: () => Effect.succeed(Option.none()),
    onSome: values => Effect.map(parseRootInstallSkillValues(values), Option.some),
  });

const scopeCommandMismatch = (
  commandPath: string,
  descriptor: AnyCommandDescriptor,
  error: unknown
) => {
  if (!ValidationError.isValidationError(error) || !ValidationError.isCommandMismatch(error)) {
    return error;
  }
  const childNames = listSubcommandNames(descriptor).map(name => `'${name}'`);
  if (childNames.length === 0) return error;

  const oneOf = childNames.length === 1 ? '' : ' one of';
  return ValidationError.commandMismatch(
    HelpDoc.p(
      `Invalid subcommand for composio ${commandPath} - use${oneOf} ${childNames.join(', ')}`
    )
  );
};

const refineRootCommandMismatch = (
  argv: ReadonlyArray<string>,
  visibility: CommandVisibility,
  originalError: ValidationError.ValidationError
) => {
  const rootCommandName = argv[2];
  if (!rootCommandName || !ValidationError.isCommandMismatch(originalError)) {
    return Effect.fail(originalError);
  }

  const rootCommand = Arr.findFirst(getVisibleRootCommands(visibility), command =>
    hasCommandName(command, rootCommandName)
  );
  if (Option.isNone(rootCommand)) {
    return Effect.fail(originalError);
  }

  const nestedCommandName = argv[3];
  const nestedDevCommand =
    rootCommandName === 'dev' && visibility.isDevModeEnabled && nestedCommandName
      ? Arr.findFirst(devSubcommands, command => hasCommandName(command, nestedCommandName))
      : Option.none();
  const descriptor = Option.match(nestedDevCommand, {
    onNone: () => rootCommand.value.descriptor,
    onSome: command => command.descriptor,
  });
  const commandPath = Option.isSome(nestedDevCommand)
    ? `${rootCommandName} ${nestedCommandName}`
    : rootCommandName;

  return Effect.fail(scopeCommandMismatch(commandPath, descriptor, originalError));
};

export const parseExecuteInputHelpSlug = (argv: ReadonlyArray<string>): string | undefined => {
  const args = Arr.drop(argv, 2);
  const isRootExecute = args[0] === 'execute';
  const isDevExecute = args[0] === 'dev' && args[1] === 'playground-execute';
  if (!isRootExecute && !isDevExecute) return undefined;

  const hasHelp = args.includes('--help') || args.includes('-h');
  if (!hasHelp) return undefined;

  const findSlug = (tail: ReadonlyArray<string>): string | undefined =>
    Arr.matchLeft(tail, {
      onEmpty: () => undefined,
      onNonEmpty: (token, rest) => {
        if (token === '--') {
          return Option.getOrUndefined(
            Option.filter(Arr.head(rest), candidate => !candidate.startsWith('-'))
          );
        }
        if (token === '--help' || token === '-h') {
          return findSlug(rest);
        }
        if (HashSet.has(TOOLS_EXECUTE_VALUE_OPTIONS, token)) {
          return findSlug(Arr.drop(rest, 1));
        }
        if (token.startsWith('-')) {
          return findSlug(rest);
        }
        return token;
      },
    });

  return findSlug(Arr.drop(args, isRootExecute ? 1 : 2));
};

const VERSION_FLAGS: ReadonlySet<string> = new Set(['--version', '-v']);

/**
 * `composio --version` and `composio -v` are spellings of the `version` command: the flag is
 * rewritten before parsing so all three share one handler and print byte-identical output,
 * independent of how the CLI framework renders its own built-in version flag.
 */
const normalizeVersionFlag = (argv: ReadonlyArray<string>): ReadonlyArray<string> => {
  const [first, ...rest] = argv.slice(2);
  return first !== undefined && VERSION_FLAGS.has(first)
    ? [...argv.slice(0, 2), 'version', ...rest]
    : argv;
};

const normalizeListenStreamFlag = (argv: ReadonlyArray<string>): ReadonlyArray<string> => {
  const head = Arr.take(argv, 2);
  const args = Arr.drop(argv, 2);
  const isListen = args[0] === 'listen';
  if (!isListen) {
    return argv;
  }

  return Arr.appendAll(
    head,
    Arr.map(args, (token, index) => {
      const next = args[index + 1];
      return token === '--stream' && (next === undefined || next.startsWith('-'))
        ? '--stream='
        : token;
    })
  );
};

const parseBooleanFlag = (argument: string, name: string): Option.Option<boolean> => {
  if (argument === name || argument === `${name}=true`) {
    return Option.some(true);
  }
  return argument === `${name}=false` ? Option.some(false) : Option.none();
};

/**
 * Splits the hidden debug flags off argv and returns their parsed values.
 *
 * The values are inputs to the command that follows — `src/commands/index.ts` provides them as
 * `CliDebugFlags` — rather than process-wide state, so an explicit `--perf-debug=false` on one
 * invocation cannot leak into the next.
 */
const normalizeHiddenDebugFlags = (
  argv: ReadonlyArray<string>
): { readonly argv: ReadonlyArray<string>; readonly overrides: CliDebugFlagOverrides } => {
  const retainedArgs: Array<string> = [];
  let perfDebug: boolean | undefined;
  let toolDebug: boolean | undefined;
  let acpOnly: boolean | undefined;

  for (const argument of Arr.drop(argv, 2)) {
    const parsedPerfDebug = Option.getOrUndefined(parseBooleanFlag(argument, '--perf-debug'));
    if (parsedPerfDebug !== undefined) {
      perfDebug = parsedPerfDebug;
      continue;
    }
    const parsedToolDebug = Option.getOrUndefined(parseBooleanFlag(argument, '--tool-debug'));
    if (parsedToolDebug !== undefined) {
      toolDebug = parsedToolDebug;
      continue;
    }
    const parsedAcpOnly = Option.getOrUndefined(parseBooleanFlag(argument, '--acp-only'));
    if (parsedAcpOnly !== undefined) {
      acpOnly = parsedAcpOnly;
      continue;
    }
    retainedArgs.push(argument);
  }

  return {
    argv: Arr.appendAll(Arr.take(argv, 2), retainedArgs),
    overrides: { perfDebug, toolDebug, acpOnly },
  };
};

const isRootHelp = (argv: ReadonlyArray<string>): boolean => {
  const args = argv.slice(2);
  return (
    args.length === 0 ||
    (args.length >= 1 &&
      args.length <= 2 &&
      (args[0] === '--help' || args[0] === '-h') &&
      (args.length === 1 || parseHelpLevel(args[1]) !== undefined))
  );
};

const isGenerateGraph = (argv: ReadonlyArray<string>): boolean => {
  const args = argv.slice(2);
  return args.length === 2 && args[0] === 'debug' && args[1] === 'generate-graph';
};

const isDebugApiInfo = (argv: ReadonlyArray<string>): boolean => {
  const args = argv.slice(2);
  return args.length === 2 && args[0] === 'debug' && args[1] === 'api-info';
};

const isDebugWhoIsMyMaster = (argv: ReadonlyArray<string>): boolean => {
  const args = argv.slice(2);
  return args.length === 2 && args[0] === 'debug' && args[1] === 'who-is-my-master';
};

const normalizeDangerouslyAllowFlag = (argv: ReadonlyArray<string>) => {
  const retainedArgs: Array<string> = [];
  let dangerouslyAllow = false;
  for (const argument of Arr.drop(argv, 2)) {
    if (argument === '--dangerously-allow') {
      dangerouslyAllow = true;
    } else {
      retainedArgs.push(argument);
    }
  }

  return {
    argv: Arr.appendAll(Arr.take(argv, 2), retainedArgs),
    dangerouslyAllow,
  };
};

const isHelpRequest = (args: ReadonlyArray<string>) =>
  args.includes('--help') || args.includes('-h');

const isDevModeOnlyInvocation = (args: ReadonlyArray<string>) => {
  if (args[0] !== 'dev') return false;
  if (isHelpRequest(args)) return true;
  if (args.length === 1) return true;
  if (args.length === 2 && (args[1] === '--mode' || args[1].startsWith('--mode='))) return true;
  if (args.length === 3 && args[1] === '--mode') return true;
  return false;
};

const isDangerousDevCommand = (args: ReadonlyArray<string>): boolean => {
  if (args[0] !== 'dev' || isHelpRequest(args)) return false;

  if (args[1] === 'triggers') {
    return args[2] === 'disable';
  }

  return false;
};

const printCommandHintGraph = Effect.suspend(() =>
  Effect.flatMap(TerminalUI, ui =>
    ui.output(JSON.stringify(renderCommandHintGraph(), null, 2), { force: true })
  )
);

const printDebugApiInfo = Effect.gen(function* () {
  const ui = yield* TerminalUI;
  const confirmed = yield* ui.confirm(
    'This will print your current CLI API key and scoped identifiers to stdout. Continue?',
    { defaultValue: false }
  );
  if (!confirmed) {
    return yield* rootCommandError('Aborted printing API credentials.');
  }
  const ctx = yield* ComposioUserContext;
  const apiKey = Option.getOrUndefined(ctx.data.apiKey);
  if (!apiKey) {
    return yield* rootCommandError('No user API key found in the current CLI session.');
  }
  const orgId = Option.getOrUndefined(ctx.data.orgId);
  const consumerProject = yield* resolveCommandProject({ mode: 'consumer' }).pipe(
    Effect.mapError(formatResolveCommandProjectError),
    Effect.option
  );
  return yield* ui.output(
    JSON.stringify(
      {
        apiKey,
        orgId: orgId ?? null,
        consumerUserId:
          Option.isSome(consumerProject) && consumerProject.value.projectType === 'CONSUMER'
            ? (consumerProject.value.consumerUserId ?? null)
            : null,
      },
      null,
      2
    ),
    { force: true }
  );
});

const printDetectedMaster = Effect.gen(function* () {
  const ui = yield* TerminalUI;
  const master = yield* detectMasterFromHost;
  yield* ui.output(JSON.stringify({ master }, null, 2), { force: true });
});

const printDevModeDisabled = Effect.gen(function* () {
  const ui = yield* TerminalUI;
  yield* ui.log.error('Developer mode is off.');
  yield* ui.log.step('Run `composio dev --mode on` in an interactive terminal to enable it.');
});

/**
 * Values the CLI bootstrap resolved before the root command runs and that the command tree needs
 * as an input. Empty for callers that drive the root command on their own (tests, `--install-skill`
 * style entry points), which is why every field is optional.
 */
export type RootCommandBootstrap = {
  /** Run id minted for a `composio run` invocation, shared with its telemetry events. */
  readonly runId?: string;
};

export const runWithConfig = Effect.gen(function* () {
  const cliUserConfig = yield* ComposioCliUserConfig;
  const visibility: CommandVisibility = {
    isDevModeEnabled: cliUserConfig.isDevModeEnabled(),
    isExperimentalFeatureEnabled: feature => cliUserConfig.isExperimentalFeatureEnabled(feature),
  };
  const version = yield* getVersion;
  configureCliAnalyticsReleaseVersion(version);
  const rootCommand = withBackgroundUpdateCheck(buildRootCommand(visibility));
  const run = Command.run(rootCommand, {
    name: 'composio',
    executable: 'composio',
    version,
  });

  const routeRootCommand = (normalizedArgv: ReadonlyArray<string>, dangerouslyAllow: boolean) => {
    const args = normalizedArgv.slice(2);
    if (isRootHelp(normalizedArgv)) {
      return printRootHelp(visibility, parseHelpLevel(normalizedArgv[3]) ?? 'default');
    }
    const subHelp = matchSubcommandHelp(normalizedArgv, visibility);
    if (subHelp) {
      const helpLevel = parseHelpLevel(normalizedArgv[normalizedArgv.length - 1]) ?? 'default';
      return printSubcommandHelp(subHelp, visibility, helpLevel);
    }
    const parallelExecute = runParallelToolsExecuteFromArgv(normalizedArgv);
    if (parallelExecute) {
      return parallelExecute;
    }
    if (isGenerateGraph(normalizedArgv)) {
      return printCommandHintGraph;
    }
    if (isDebugApiInfo(normalizedArgv)) {
      return printDebugApiInfo;
    }
    if (isDebugWhoIsMyMaster(normalizedArgv)) {
      return printDetectedMaster;
    }
    const executeHelpSlug = parseExecuteInputHelpSlug(normalizedArgv);
    if (executeHelpSlug) {
      return showToolsExecuteInputHelp(executeHelpSlug);
    }
    if (!visibility.isDevModeEnabled && args[0] === 'dev' && !isDevModeOnlyInvocation(args)) {
      return printDevModeDisabled;
    }
    if (isDangerousDevCommand(args)) {
      return Effect.gen(function* () {
        const ui = yield* TerminalUI;
        if (!cliUserConfig.areDeveloperDangerousCommandsEnabled()) {
          yield* ui.log.error('This developer command is disabled by config.');
          yield* ui.log.step(
            'Set `developer.destructive_actions` to `true` in `~/.composio/config.json` to allow dangerous developer commands.'
          );
          return;
        }
        if (!dangerouslyAllow) {
          yield* ui.log.error('This developer command requires explicit acknowledgement.');
          yield* ui.log.step('Re-run the command with `--dangerously-allow`.');
          return;
        }
        return yield* run(normalizedArgv);
      });
    }
    return preflightParse(rootCommand, normalizedArgv).pipe(
      Effect.matchEffect({
        onFailure: error =>
          ValidationError.isCommandMismatch(error)
            ? refineRootCommandMismatch(normalizedArgv, visibility, error)
            : run(normalizedArgv),
        onSuccess: () => run(normalizedArgv),
      })
    );
  };

  return (argv: ReadonlyArray<string>, bootstrap: RootCommandBootstrap = {}) => {
    const { argv: argvWithoutDangerouslyAllow, dangerouslyAllow } =
      normalizeDangerouslyAllowFlag(argv);
    const { argv: normalizedArgv, overrides } = normalizeHiddenDebugFlags(
      normalizeListenStreamFlag(normalizeVersionFlag(argvWithoutDangerouslyAllow))
    );

    return parseRootInstallSkillRequest(normalizedArgv).pipe(
      Effect.flatMap(
        Option.match({
          onNone: () => routeRootCommand(normalizedArgv, dangerouslyAllow),
          onSome: installSkill,
        })
      ),
      Effect.provide(Layer.merge(cliDebugFlagsLayer(overrides), cliRunIdLayer(bootstrap.runId)))
    );
  };
});