Getting Started

Welcome to the Olympix CLI usage guide! This guide will help you quickly get started with the command-line interface for the Olympix Static Analyzer, Test Generator, and BugPoCer.

CLI Commands Overview

When you run the Olympix CLI, you have access to several commands:

Interactive Mode (TUI):

olympix (no arguments): Launch the interactive tool selection menu — pick any tool, monitor live sessions, reconnect to results
static-analysis: Interactive static analysis — file selection, scan, results
unit-testing: Unit test session manager — list, reconnect, or start new
mutation-testing: Mutation test session manager — list, reconnect, or start new
fuzz-testing: Interactive fuzz test generator
bug-pocer: BugPocer session manager — start, reconnect, review findings

Direct Commands (non-interactive, for scripting/CI):

analyze: Perform code analysis
generate-unit-tests: Generate unit tests
generate-mutation-tests: Generate mutation tests
generate-fuzz-tests: Generate fuzz tests
show-vulnerabilities: Show the vulnerability types that the analyzer aims to find

Agent Mode (AI integrations):

--agent (or -am): Run any command in agent mode — structured JSON protocol over stdin/stdout for AI coding assistants
sessions --agent: List all active sessions across all services

Authentication:

login: Log in with email verification code
login-sso: Log in with Okta SSO (enterprise)
generate-api-token: Generate an API token for CI/CD

Organization Management (admin only):

configure-sso: Configure Okta SSO for your organization
show-sso: View current SSO configuration
enable-sso: Enable SSO with existing configuration
disable-sso: Disable SSO for your organization
org-seats: View organization seat usage
org-list-users: List all users in your organization
org-invite-user: Invite a user to your organization
org-remove-user: Remove a user from your organization
org-set-admin: Promote or demote organization admin

Utility:

version: Show CLI version

Analysis Options

When using the analyze command, you can customize the analysis with the following options:

-w | --workspace-path
Defines the root project directory path. This helps in providing more accurate vulnerability analysis.
Default: current directory
-p | --path
Defines the Solidity project directory path to be analyzed. Can be used multiple times.
Default: 'contracts' and 'src' directories if they exist, otherwise the workspace directory
-f | --output-format
Defines the result output format. Supported formats: tree, json, sarif, email.
Default: tree
-o | --output-path
Defines the result output directory path (enabled only for json and sarif formats).
Default: Results are shown directly in the terminal
--no-<vulnerability id>
Defines the vulnerabilities to be ignored. Can be used multiple times.
Default: Ignores nothing

Unit Tests Generation Options

When generating unit tests, you can use these options:

-w | --workspace-path Defines the root project directory path.
Default: current directory
-env | --include-dot-env: If included, sends the env file data along with smart contracts (This is to pass secrets such as private keys/RPC urls/API keys etc. which are often need for fork testing). To specify a custom env file, include the —env-file argument.
--env-file: Defines the path of the file containing the environment variables. Make sure to follow foundry’s .env format guidelines. Doesn’t do anything if ‘—include-dot-env’ is not set. Default: .env
-ext, --extension: This allows you to specify additional file extensions to be included in the analysis. You can use this option multiple times to add more extensions. For example: --extra-extension .json --extra-extension .txt. By default, only .sol/.t.sol and/or foundry.toml files are uploaded.
-ca | --confirm-all
Confirm as ‘yes’ for all interactive questions.

Mutation Tests Generation Options

Mutation testing supports both Foundry and Hardhat projects. The framework is auto-detected based on your project configuration.

When generating mutation tests, you have the following options:

-w | --workspace-path
Defines the root project directory path.
Default: current directory
-p | --path
Defines the Solidity file path to run the mutation tests. Can be used multiple times.
-t | --timeout
Sets a timeout (in seconds) for each mutant. This prevents infinite loops or hangs.
Default: 300 seconds
Allowed Range: 10 - 500 seconds
-env | --include-dot-env: If included, sends the env file data along with smart contracts (This is to pass secrets such as private keys/RPC urls/API keys etc. which are often need for fork testing). To specify a custom env file, include the —env-file argument.
--env-file: Defines the path of the file containing the environment variables. Make sure to follow foundry’s .env format guidelines. Doesn’t do anything if ‘—include-dot-env’ is not set. Default: .env
-ext, --extension: This allows you to specify additional file extensions to be included in the analysis. You can use this option multiple times to add more extensions. For example: --extra-extension .json --extra-extension .txt. By default, only .sol/.t.sol and/or foundry.toml files are uploaded.

BugPoCer Options

When using the bug-pocer command for AI-powered vulnerability detection and PoC generation:

-w | --workspace-path Defines the root project directory path. Default: current directory
-env | --include-dot-env: If included, sends the env file data along with smart contracts (This is to pass secrets such as private keys/RPC urls/API keys etc. which are often needed for fork testing). To specify a custom env file, include the —env-file argument.
--env-file: Defines the path of the file containing the environment variables. Make sure to follow foundry’s .env format guidelines. Doesn’t do anything if ‘—include-dot-env’ is not set. Default: .env
-ext, --extension: This allows you to specify additional file extensions to be included in the analysis. You can use this option multiple times to add more extensions.
-rc | --rebuild-context: Force a fresh project-context build, ignoring the context cache.
-sp | --skip-preflight: Skip the local pre-flight build check before upload.
-ca | --confirm-all: Auto-confirm scope, documentation, cache, and pre-flight prompts (non-interactive; implied in CI).
--diff-base <git ref> / --diff-target <git ref>: Scan only the code changed between two git refs (diff mode). --diff-target requires --diff-base.
--framework foundry|hardhat: Pin the framework for a multiframework repo (one with both a foundry.toml and a hardhat.config.*).

See the BugPoCer documentation for full details on these options.

Usage Examples

# Interactive mode (TUI) — launch tool selection menu
olympix

# Interactive tool commands
olympix static-analysis [-w | --workspace-path <workspace directory>]
olympix unit-testing [-w | --workspace-path <workspace directory>]
olympix mutation-testing [-w | --workspace-path <workspace directory>]
olympix fuzz-testing [-w | --workspace-path <workspace directory>]
olympix bug-pocer [-w | --workspace-path <workspace directory>]

# Direct commands (non-interactive, for scripting/CI)
olympix analyze [-w | --workspace-path <workspace directory>] [-p | --path <analysis directory>] [-f | --output-format <output format>] [-o | --output-path <output directory>] [--no-<vulnerability id>]
olympix generate-unit-tests [-w | --workspace-path <workspace directory>] [-ca | --confirm-all] [-env | --include-dot-env] [--env-file <env file path>] [-ext | --extension .<extension-to-include>]
olympix generate-mutation-tests [-w | --workspace-path <workspace directory>] [-p | --path <solidity file path>] [-t | --t <timeout>] [-env | --include-dot-env] [--env-file <env file path>] [-ext | --extension .<extension-to-include>]
olympix generate-fuzz-tests [-w | --workspace-path <workspace directory>] [-p | --path <solidity file path>] [-cm | --coverage-mode <path|branch>] [-cl | --chain-length <length>]

# Agent mode (AI integrations)
olympix bug-pocer --agent
olympix unit-testing --agent
olympix sessions --agent

# Login with email
olympix login [-e | --email <user email>]

# Login with Okta SSO (enterprise)
olympix login-sso [-e | --email <user email>]

# Organization management (admin only)
olympix org-seats
olympix org-list-users
olympix org-invite-user [-e | --email <user email>]
olympix org-remove-user [-u | --user-id <user id>]
olympix org-set-admin [-u | --user-id <user id>] [--grant | --revoke]
olympix configure-sso
olympix show-sso
olympix enable-sso
olympix disable-sso

Helpful Links

Installation Get started by installing the CLI binaries and the VSCode extension.

Interactive Mode (TUI) Launch the interactive tool selection menu and session manager.

Agent Mode Drive the CLI programmatically with a structured JSON protocol for AI coding assistants.

Claude Code Plugin Install the Olympix skills for Claude Code — run every tool through agent mode automatically.

Unit Test Generation Learn how to generate unit tests for your smart contracts using the Olympix Unit Test Generator.

Mutation Tests Generation Find out how to generate mutation tests to assess your unit test quality.

BugPoCer Learn about the AI-powered vulnerability scanner with automated PoC generation.

SSO Setup Configure Okta Single Sign-On for your organization.

Organization Management Manage users, seats, and admin roles for your organization.

With these commands and options at your disposal, you’re well-equipped to leverage Olympix for efficient static analysis and robust test generation. If you have any questions, our support team is ready to help at contact@olympix.ai.