@cto.ai/ops

![](https://cto.ai/static/sdk-banner.png) # ops 💻 CTO.ai Ops - The CLI built for Teams 🚀 ![Release](https://github.com/cto-ai/cli/workflows/Test%20%26%20Release/badge.svg) [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io) [![Version](https://img.shields.io/npm/v/ops.svg)](https://npmjs.org/package/ops) [![Downloads/week](https://img.shields.io/npm/dw/ops.svg)](https://npmjs.org/package/ops) [![License](https://img.shields.io/npm/l/ops.svg)](https://github.com/cto.ai/ops/blob/master/package.json)  * [ops](#ops) * [Usage](#usage) * [Commands](#commands) * [Testing](#testing) * [Releases](#releases)  # Usage  ```sh-session $ npm install -g @cto.ai/ops $ ops COMMAND running command... $ ops (-v|--version|version) @cto.ai/ops/1.19.23 linux-x64 node-v16.20.2 $ ops --help [COMMAND] USAGE $ ops COMMAND ... ```  # Commands  * [`ops account:reset`](#ops-accountreset) * [`ops account:signin`](#ops-accountsignin) * [`ops account:signout`](#ops-accountsignout) * [`ops account:signup`](#ops-accountsignup) * [`ops account:support`](#ops-accountsupport) * [`ops add [OPNAME]`](#ops-add-opname) * [`ops build [PATH]`](#ops-build-path) * [`ops certs CERTIFICATETYPE NAMEORPATH`](#ops-certs-certificatetype-nameorpath) * [`ops cleanup [WORKFLOW]`](#ops-cleanup-workflow) * [`ops configs:delete`](#ops-configsdelete) * [`ops configs:list`](#ops-configslist) * [`ops configs:set`](#ops-configsset) * [`ops generate:token`](#ops-generatetoken) * [`ops help [COMMAND]`](#ops-help-command) * [`ops init [NAME]`](#ops-init-name) * [`ops list`](#ops-list) * [`ops publish PATH`](#ops-publish-path) * [`ops remove WORKFLOW`](#ops-remove-workflow) * [`ops run [NAMEORPATH]`](#ops-run-nameorpath) * [`ops search [FILTER]`](#ops-search-filter) * [`ops secrets:delete`](#ops-secretsdelete) * [`ops secrets:list`](#ops-secretslist) * [`ops secrets:register`](#ops-secretsregister) * [`ops secrets:set`](#ops-secretsset) * [`ops secrets:unregister`](#ops-secretsunregister) * [`ops start [NAMEORPATH]`](#ops-start-nameorpath) * [`ops status`](#ops-status) * [`ops stop [RUNID]`](#ops-stop-runid) * [`ops team:create`](#ops-teamcreate) * [`ops team:info`](#ops-teaminfo) * [`ops team:invite`](#ops-teaminvite) * [`ops team:join`](#ops-teamjoin) * [`ops team:leave`](#ops-teamleave) * [`ops team:list`](#ops-teamlist) * [`ops team:remove [MEMBER]`](#ops-teamremove-member) * [`ops team:switch [TEAMNAME]`](#ops-teamswitch-teamname) * [`ops update`](#ops-update) * [`ops whoami`](#ops-whoami) ## `ops account:reset` Reset your password. ``` USAGE $ ops account:reset ``` ## `ops account:signin` Log in to your account. ``` USAGE $ ops account:signin OPTIONS -h, --help show CLI help -i, --interactive Interactive Mode -p, --password=password Password -t, --team=team Team Name -u, --user=user Username or email ``` ## `ops account:signout` Log out from your account. ``` USAGE $ ops account:signout OPTIONS -h, --help show CLI help ``` ## `ops account:signup` Creates an account to use with ops CLI. ``` USAGE $ ops account:signup OPTIONS -h, --help show CLI help ``` ## `ops account:support` Contact our support team with questions. ``` USAGE $ ops account:support OPTIONS -h, --help show CLI help ``` ## `ops add [OPNAME]` Add a workflow to your team. ``` USAGE $ ops add [OPNAME] ARGUMENTS OPNAME Name of the public workflow to be added to your team. It should be of the format - @teamname/workflowName:versionName OPTIONS -h, --help show CLI help ``` ## `ops build [PATH]` Build your workflow for sharing. ``` USAGE $ ops build [PATH] ARGUMENTS PATH Path to the workflow you want to build. OPTIONS -h, --help show CLI help --nocache Do not use cache when building the image --ops=workflows List of workflows from ops.yml you want to build. example: ops build ./ops.yml --ops commandName serviceName pipelineName ``` ## `ops certs CERTIFICATETYPE NAMEORPATH` Save an SSL certificate and key for your service ``` USAGE $ ops certs CERTIFICATETYPE NAMEORPATH ARGUMENTS CERTIFICATETYPE (ssl) The type of certificate to store NAMEORPATH Name or path of the service to save SSL for. OPTIONS -h, --help Show help screen --cert-file=cert-file Path to your certificate file --key-file=key-file Path to your key file ``` ## `ops cleanup [WORKFLOW]` Clean up locally cached docker images. ``` USAGE $ ops cleanup [WORKFLOW] ARGUMENTS WORKFLOW Name of the workflow to be cleaned up OPTIONS -h, --help show CLI help ``` ## `ops configs:delete` Delete a config stored for the active team ``` USAGE $ ops configs:delete OPTIONS -h, --help show CLI help -k, --key=key Secret Key Name ``` ## `ops configs:list` List all the configs that are stored for the active team ``` USAGE $ ops configs:list OPTIONS -h, --help show CLI help ``` ## `ops configs:set` Add a new config key & value ``` USAGE $ ops configs:set OPTIONS -f, --from-file=from-file path to a file containing the value of the config to set -k, --key=key the key of the config to set -v, --value=value the value of the config to set ``` ## `ops generate:token` Generate a long live access token. ``` USAGE $ ops generate:token OPTIONS -h, --help show CLI help ``` ## `ops help [COMMAND]` display help for ops ``` USAGE $ ops help [COMMAND] ARGUMENTS COMMAND command to show help for OPTIONS --all see all commands in CLI ``` _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v3.2.18/src/commands/help.ts)_ ## `ops init [NAME]` Create a new Workflow ``` USAGE $ ops init [NAME] ARGUMENTS NAME provide a name or pass a github url to a template OPTIONS -h, --help show CLI help -j, --jobs generate local template files for pipeline jobs -k, --kind=kind the kind of Application to create (command, pipeline, etc.) -t, --template=template the name of the template to use ``` ## `ops list` Lists the Workflows you have in your team. ``` USAGE $ ops list OPTIONS -h, --help show CLI help ``` ## `ops publish PATH` Publish a workflow to your team. ``` USAGE $ ops publish PATH ARGUMENTS PATH Path to the workflow you want to publish. OPTIONS -c, --changelog=changelog Provide a publish changelog -h, --help show CLI help -o, --ops=workflows Provide the list of workflows that you want to publish. --nocache Do not use cache when building the image ``` ## `ops remove WORKFLOW` Remove a workflow from your team. ``` USAGE $ ops remove WORKFLOW ARGUMENTS WORKFLOW The name and version of the workflow you want to remove. E.g. my-workflow:0.1.0 Don't include team name or version if using the --all flag OPTIONS -h, --help show CLI help --all Allows you to remove all versions of a workflow on your current team. ``` ## `ops run [NAMEORPATH]` Run a workflow from your team or the registry. ``` USAGE $ ops run [NAMEORPATH] ARGUMENTS NAMEORPATH Name or path of the workflow you want to run. OPTIONS -B, --batch Runs the workflow in non-interactive batch mode. -b, --build Builds the workflow before running. Must provide a path to the workflow. -h, --help show CLI help --nocache Do not use cache when building the image ``` ## `ops search [FILTER]` Search for workflows in our registry. ``` USAGE $ ops search [FILTER] ARGUMENTS FILTER Filter results by workflow name or description. OPTIONS -h, --help show CLI help ``` ## `ops secrets:delete` Delete a secret stored for the active team ``` USAGE $ ops secrets:delete OPTIONS -h, --help show CLI help -k, --key=key Secret Key Name ``` ## `ops secrets:list` List all the keys that are stored for the active team ``` USAGE $ ops secrets:list OPTIONS -h, --help show CLI help ``` ## `ops secrets:register` Register a secrets provider for a team ``` USAGE $ ops secrets:register ``` ## `ops secrets:set` Add a key & value ``` USAGE $ ops secrets:set OPTIONS -f, --from-file=from-file path to a file containing the value of the secret to set -k, --key=key the key of the secret to set -v, --value=value the value of the secret to set ``` ## `ops secrets:unregister` Unregister a secrets provider for a team ``` USAGE $ ops secrets:unregister ``` ## `ops start [NAMEORPATH]` Start a service, pipeline or command on our cloud. ``` USAGE $ ops start [NAMEORPATH] ARGUMENTS NAMEORPATH Name or path of the workflow you want to run. OPTIONS -h, --help show CLI help ``` ## `ops status` See the status of currently running cloud services ``` USAGE $ ops status OPTIONS -h, --help show CLI help ``` ## `ops stop [RUNID]` Stop a service, pipeline or command running in The Ops Cloud ``` USAGE $ ops stop [RUNID] ARGUMENTS RUNID Run ID of the service, pipeline or command to stop OPTIONS -h, --help show CLI help ``` ## `ops team:create` Create your team. ``` USAGE $ ops team:create OPTIONS -h, --help show CLI help -n, --name=name ``` ## `ops team:info` Shows basic team information for the team you are currently on. ``` USAGE $ ops team:info OPTIONS -h, --help show CLI help ``` ## `ops team:invite` Invite your team members. ``` USAGE $ ops team:invite OPTIONS -h, --help show CLI help -i, --invitees=invitees A comma-separated string of usernames/emails we want to invite. E.g. ("user1, user2@gmail.com, user3@something") ``` ## `ops team:join` Accept an invite to join a team. ``` USAGE $ ops team:join ``` ## `ops team:leave` Leave current team. ``` USAGE $ ops team:leave OPTIONS -h, --help show CLI help ``` ## `ops team:list` Shows the list of your teams. ``` USAGE $ ops team:list OPTIONS -h, --help show CLI help ``` ## `ops team:remove [MEMBER]` Remove your team members. ``` USAGE $ ops team:remove [MEMBER] ARGUMENTS MEMBER The username of the team member you want to remove from the team. OPTIONS -h, --help show CLI help ``` ## `ops team:switch [TEAMNAME]` Switch your currently active team. ``` USAGE $ ops team:switch [TEAMNAME] ARGUMENTS TEAMNAME Team Name OPTIONS -h, --help show CLI help ``` ## `ops update` Update The Ops CLI. ``` USAGE $ ops update OPTIONS -h, --help show CLI help ``` ## `ops whoami` Display your user information ``` USAGE $ ops whoami OPTIONS -h, --help show CLI help ```  ### OClif Source Repo Useful reference for writing tests: * https://github.com/oclif/command/blob/master/src/command.ts * https://github.com/oclif/config/blob/master/src/plugin.ts # Testing Isolate tests (run only specific tests in that file): test.only('it should run only tests suffixed with .only', async () => { ## Unit Tests (`test` directory) ### How to run Unit Tests 1. `npm test` or `npm t` ### Tips Run a single unit test, or filter them by filename: npx jest --testPathPattern=keycloak ## E2E Tests (`test_e2e` directory) The CLI has a number of robused E2E tests that are hosted inside of CTO.ai's private CI/CD infra. We are planning to expose this system via Github Actions in the future, but for now, a CTO.ai team member will review your PR and test coverage. ### How to run E2E tests locally The default test server is staging, but you can override this by passing in your own `OPS_REGISTRY_HOST` and `OPS_API_HOST` values from your shell config. Run tests against staging (as part of the CTO.ai platform developer workflow): 1. Run `npm run configdev` to point the ops binary at the development Typescript app (instead of the production Javascript bundle) 2. Ensure you have a `.env.staging` file (you can generate one by running scripts/make-env.sh) 3. Set your `NODE_ENV` to 'staging': `export NODE_ENV=staging` 4. `npm run test:e2e` Run tests against Minikube (as part of the CTO.ai platform developer workflow): 1. Create a user in Keycloak with the following credentials: ``` - username: 'existing_user' - email: 'e2e_existing_user1@cto.ai' - password: 'password' ``` 2. Change the userID in `test_e2e/utils/constants.ts EXISTING_USER_ID` to Step 1's userID 3. Create `existing_user` team in Database if haven't already 4. Change the teamID in `teste2e/utils/constants.ts EXISTING_TEAM_ID` to step 3's teamID 5. Create a `cto.ai` team in Database if haven't already 6. Publish this following command: ``` - Team: ‘cto.ai’ - name: ‘github’ - version: ‘latest’ - public: true ``` 7. Publish the `write_a_file_op` command found in `test_e2e/sample_ops/write_a_file_op` 8. Publish the `echo_message_workflow` workflow found in `test_e2e/sample_ops/echo_message_workflow` 9. Add the `ops-cli-confidential` client to Keycloak. The `ops-cli-confidential.json` file can be found in Keybase 10. Run `npm run configdev` to point the ops binary at the development Typescript app (instead of the production Javascript bundle) 11. Ensure you have a `.env.test` file (you can generate one by running scripts/make-env.sh) 12. Modify the vars in `.env.test` to match your minikube IP 13. Set your `NODE_ENV` to 'test': `export NODE_ENV=test` 14. `npm run test:e2e` ### Tips 1 Run a single E2E test, or filter test files by filename: npm run test:e2e --testPathPattern=signin # Releases This CLI application is distributed via public Node Package Manager registry. Any non-trivial changes should be tested by first releasing to the Release Candidate package https://www.npmjs.com/package/@cto.ai/ops-rc before releasing to the official https://www.npmjs.com/package/@cto.ai/ops ## Release Candidate Checklist 1. Switch to the branch containing the changes to be released (it should not yet be merged to `master`) 2. Ensure the code passes all tests by running `npm run test` 3. Edit `package.json` and update `name` to `@cto.ai/ops-rc` and `version` to the next successive version (e.g. if the current published `ops` version is `1.20.3`, the next rc version should be set to `1.20.4-rc.0`, `1.20.4-rc.1`, etc for each successive release candidate publish targeting the next official version to be eventually released to `ops`) 4. Run `npm i` to integrate above changes into `package-lock.json` 5. Log in to NPM (`npm login`) with your NPM credentials. Make sure your user is part of the `ops-rc` team. If not, your user can be added by logging in with the `cto.ai-admin` account (credentials in LastPass) 6. Publish the package to `@cto.ai/ops-rc` by running `npm publish` 7. Confirm the updated version appears on https://www.npmjs.com/package/@cto.ai/ops-rc 8. You can now test the published package by installing it: `npm i -g @cto.ai/ops-rc` (it is recommended you first remove existing `ops` by running: - `npm uninstall -g @cto.ai/ops` - `rm -rf $(which ops)` 9. Note that there will be a message stating that an update is available because the CLI code internally checks against the published version of `ops` (not `ops-rc`) 10. Point the installed binary CLI to STAGING by sourcing the `.env.staging` file as follows: - `source .env.staging` - `export $(cut -d= -f1 .env.staging)` - Running `ops account:signin` should now sign you into staging 11. Once all code changes have been tested and confirmed to work on staging, you can switch the CLI to point to PRODUCTION by running: - `unset $(cut -d= -f1 .env.staging)` - Running `ops account:signin` should sign you into production 12. Once all code changes have been tested and confirmed to work in production, the package may be deployed to the `ops` package (see next section). ## Release Production Checklist Releases are now handled by `.gitlab/workflows/release.yml`, which is triggered via a pushed tag that matches `v*`. This workflow will run `npm publish` and publish the current semantic version in the `package.json`. To simplify things, we've added the tag push command as a post hook to the `npm version` script. Steps to trigger a successful release: 1. Ensure that `name` in `package.json` has been set to `ops` 2. Run `npm version v{package_version}` (this will version `package.json` and update `README.md` to reflect that version and then create and push the tag to GitHub)