flyte 0.2.0b5__py3-none-any.whl → 0.2.0b8__py3-none-any.whl

flyte/cli/_common.py

@@ -19,11 +19,13 @@ from rich.table import Table
 from rich.traceback import Traceback
 
 import flyte.errors
+from flyte._logging import logger
 from flyte.config import Config
 
 PREFERRED_BORDER_COLOR = "dim cyan"
 PREFERRED_ACCENT_COLOR = "bold #FFD700"
 HEADER_STYLE = f"{PREFERRED_ACCENT_COLOR} on black"
+PANELS = False
 
 PROJECT_OPTION = click.Option(
     param_decls=["-p", "--project"],
@@ -71,11 +73,12 @@ class CLIConfig:
     This is the global state for the CLI. It is manipulated by the main command.
     """
 
+    config: Config
+    ctx: click.Context
     log_level: int | None = logging.ERROR
     endpoint: str | None = None
     insecure: bool = False
     org_override: str | None = None
-    config: Config | None = None
 
     def replace(self, **kwargs) -> CLIConfig:
         """
@@ -84,22 +87,26 @@ class CLIConfig:
         return replace(self, **kwargs)
 
     def init(self, project: str | None = None, domain: str | None = None):
-        import flyte
-
-        if self.config and self.config.task:
-            # If the config is already set, we can use it to initialize flyte
-            project = project or self.config.task.project
-            domain = domain or self.config.task.domain
-
-        flyte.init(
-            endpoint=self.endpoint,
-            insecure=self.insecure,
-            org=self.org_override,
-            project=project,
-            domain=domain,
-            config=self.config,
+        from flyte.config._config import TaskConfig
+
+        task_cfg = TaskConfig(
+            org=self.org_override or self.config.task.org,
+            project=project or self.config.task.project,
+            domain=domain or self.config.task.domain,
         )
 
+        kwargs: Dict[str, Any] = {}
+        if self.endpoint:
+            kwargs["endpoint"] = self.endpoint
+        if self.insecure is not None:
+            kwargs["insecure"] = self.insecure
+        platform_cfg = self.config.platform.replace(**kwargs)
+
+        updated_config = self.config.with_params(platform_cfg, task_cfg)
+
+        logger.debug(f"Initializing CLI with config: {updated_config}")
+        flyte.init_auto_from_config(updated_config)
+
 
 class InvokeBaseMixin:
     """
@@ -316,6 +323,8 @@ def get_panel(title: str, renderable: Any) -> Panel:
     """
     Get a panel from a list of values.
     """
+    if not PANELS:
+        return renderable
     return Panel.fit(
         renderable,
         title=f"[{PREFERRED_ACCENT_COLOR}]{title}[/{PREFERRED_ACCENT_COLOR}]",

flyte/cli/_create.py

@@ -10,7 +10,7 @@ from flyte.remote._secret import SecretTypes
 @click.group(name="create")
 def create():
     """
-    Create a new task or environment.
+    The create subcommand allows you to create resources in a Flyte deployment.
     """
 
 
@@ -32,7 +32,23 @@ def secret(
     domain: str | None = None,
 ):
     """
-    Create a new secret.
+    Create a new secret, the name of the secret is required.
+
+    Examples:
+    ```bash
+    flyte create secret my_secret --value my_value
+    ```
+    If `--from-file` is specified, the value will be read from the file instead of being provided directly.
+    Example:
+    ```bash
+    flyte create secret my_secret --from-file /path/to/secret_file
+    ```
+    Secret types can be used to create specific types of secrets. Some secrets are useful for image pull, while some
+    are `regular` / general purpose secrets.
+    Example:
+    ```bash
+    flyte create secret my_secret --type image_pull
+    ```
     """
     from flyte.remote import Secret
 
@@ -55,9 +71,19 @@ def secret(
 @click.option(
     "-o",
     "--output",
-    type=click.Path(),
-    default=Path.cwd(),
+    type=click.Path(exists=False, writable=True),
+    default=Path.cwd() / "config.yaml",
     help="Path to the output dir where the config will be saved, defaults to current directory.",
+    show_default=True,
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Force overwrite the config file if it already exists.",
+    show_default=True,
+    prompt="Are you sure you want to overwrite the config file?",
+    confirmation_prompt=True,
 )
 def config(
     output: Path,
@@ -66,14 +92,19 @@ def config(
     org: str | None = None,
     project: str | None = None,
     domain: str | None = None,
+    force: bool = False,
 ):
     """
-    Create a new config file.
+    This command creates a configuration file for Flyte CLI.
+    If the `--output` option is not specified, it will create a file named `config.yaml` in the current directory.
+    If the file already exists, it will raise an error unless the `--force` option is used.
     """
     import yaml
 
-    output_file = output / "config.yaml"
-    with open(output_file, "w") as f:
+    if output.exists() and not force:
+        raise click.BadParameter(f"Output file {output} already exists. Use --force to overwrite.")
+
+    with open(output, "w") as f:
         d = {
             "admin": {
                 "endpoint": endpoint,
@@ -87,4 +118,4 @@ def config(
         }
         yaml.dump(d, f)
 
-    click.echo(f"Config file created at {output_file}")
+    click.echo(f"Config file created at {output}")

flyte/cli/_delete.py

@@ -6,7 +6,7 @@ import flyte.cli._common as common
 @click.group(name="delete")
 def delete():
     """
-    Delete a task or environment.
+    The delete subcommand allows you to remove resources from a Flyte deployment.
     """
 
 
@@ -15,7 +15,7 @@ def delete():
 @click.pass_obj
 def secret(cfg: common.CLIConfig, name: str, project: str | None = None, domain: str | None = None):
     """
-    Delete a secret.
+    Delete a secret, the name of the secret is required.
     """
     from flyte.remote import Secret
 

flyte/cli/_deploy.py

@@ -138,5 +138,8 @@ class EnvFiles(common.FileGroup):
 
 deploy = EnvFiles(
     name="deploy",
-    help="deploy one or more environments from a python file.",
+    help="""
+    Deploy one or more environments from a python file.
+    The deploy command will create or update environments in the Flyte system.
+    """,
 )

flyte/cli/_gen.py

@@ -0,0 +1,155 @@
+from os import getcwd
+from typing import Generator, Tuple
+
+import rich_click as click
+
+import flyte.cli._common as common
+
+
+@click.group(name="gen")
+def gen():
+    """
+    Generate documentation
+    """
+
+
+@gen.command(cls=common.CommandBase)
+@click.option("--type", "doc_type", type=str, required=True, help="Type of documentation (valid: markdown)")
+@click.pass_obj
+def docs(cfg: common.CLIConfig, doc_type: str, project: str | None = None, domain: str | None = None):
+    """
+    Generate documentation
+    """
+    if doc_type == "markdown":
+        markdown(cfg)
+    else:
+        raise click.ClickException("Invalid documentation type: {}".format(doc_type))
+
+
+def walk_commands(ctx: click.Context) -> Generator[Tuple[str, click.Command], None, None]:
+    """
+    Recursively walk a Click command tree, starting from the given context.
+
+    Yields:
+        (full_command_path, command_object)
+    """
+    command = ctx.command
+
+    if not isinstance(command, click.Group):
+        yield ctx.command_path, command
+    else:
+        for name in command.list_commands(ctx):
+            subcommand = command.get_command(ctx, name)
+            if subcommand is None:
+                continue
+
+            full_name = f"{ctx.command_path} {name}".strip()
+            yield full_name, subcommand
+
+            # Recurse if subcommand is a MultiCommand (i.e., has its own subcommands)
+            if isinstance(subcommand, click.Group):
+                sub_ctx = click.Context(subcommand, info_name=name, parent=ctx)
+                yield from walk_commands(sub_ctx)
+
+
+def markdown(cfg: common.CLIConfig):
+    """
+    Generate documentation in Markdown format
+    """
+    ctx = cfg.ctx
+
+    output = []
+    output_verb_groups: dict[str, list[str]] = {}
+    output_noun_groups: dict[str, list[str]] = {}
+
+    commands = [*[("flyte", ctx.command)], *walk_commands(ctx)]
+    for cmd_path, cmd in commands:
+        output.append("")
+
+        cmd_path_parts = cmd_path.split(" ")
+
+        if len(cmd_path_parts) > 1:
+            if cmd_path_parts[1] not in output_verb_groups:
+                output_verb_groups[cmd_path_parts[1]] = []
+            if len(cmd_path_parts) > 2:
+                output_verb_groups[cmd_path_parts[1]].append(cmd_path_parts[2])
+
+        if len(cmd_path_parts) == 3:
+            if cmd_path_parts[2] not in output_noun_groups:
+                output_noun_groups[cmd_path_parts[2]] = []
+            output_noun_groups[cmd_path_parts[2]].append(cmd_path_parts[1])
+
+        output.append(f"{'#' * (len(cmd_path_parts) + 1)} {cmd_path}")
+        if cmd.help:
+            output.append("")
+            output.append(f"{cmd.help.strip()}")
+
+        if not cmd.params:
+            continue
+
+        params = cmd.get_params(click.Context(cmd))
+
+        # Collect all data first to calculate column widths
+        table_data = []
+        for param in params:
+            if isinstance(param, click.Option):
+                # Format each option with backticks before joining
+                all_opts = param.opts + param.secondary_opts
+                if len(all_opts) == 1:
+                    opts = f"`{all_opts[0]}`"
+                else:
+                    opts = "".join(
+                        [
+                            "{{< multiline >}}",
+                            "\n".join([f"`{opt}`" for opt in all_opts]),
+                            "{{< /multiline >}}",
+                        ]
+                    )
+                default_value = ""
+                if param.default is not None:
+                    default_value = f"`{param.default}`"
+                    default_value = default_value.replace(f"{getcwd()}/", "")
+                help_text = param.help.strip() if param.help else ""
+                table_data.append([opts, f"`{param.type.name}`", default_value, help_text])
+
+        if not table_data:
+            continue
+
+        # Add table header with proper alignment
+        output.append("")
+        output.append("| Option | Type | Default | Description |")
+        output.append("|--------|------|---------|-------------|")
+
+        # Add table rows with proper alignment
+        for row in table_data:
+            output.append(f"| {row[0]} | {row[1]} | {row[2]} | {row[3]} |")
+
+    output_verb_index = []
+
+    if len(output_verb_groups) > 0:
+        output_verb_index.append("| Action | On |")
+        output_verb_index.append("| ------ | -- |")
+        for verb, nouns in output_verb_groups.items():
+            entries = [f"[`{noun}`](#flyte-{verb}-{noun})" for noun in nouns]
+            output_verb_index.append(f"| `{verb}` | {', '.join(entries)}  |")
+
+    output_noun_index = []
+
+    if len(output_noun_groups) > 0:
+        output_noun_index.append("| Object | Action |")
+        output_noun_index.append("| ------ | -- |")
+        for obj, actions in output_noun_groups.items():
+            entries = [f"[`{action}`](#flyte-{action}-{obj})" for action in actions]
+            output_noun_index.append(f"| `{obj}` | {', '.join(entries)}  |")
+
+    print()
+    print("{{< grid >}}")
+    print("{{< markdown >}}")
+    print("\n".join(output_noun_index))
+    print("{{< /markdown >}}")
+    print("{{< markdown >}}")
+    print("\n".join(output_verb_index))
+    print("{{< /markdown >}}")
+    print("{{< /grid >}}")
+    print()
+    print("\n".join(output))

flyte/cli/_get.py

@@ -11,7 +11,16 @@ from . import _common as common
 @click.group(name="get")
 def get():
     """
-    Get the value of a task or environment.
+    The `get` subcommand allows you to retrieve various resources from a Flyte deployment.
+
+    You can get information about projects, runs, tasks, actions, secrets, and more.
+    Each command supports optional parameters to filter or specify the resource you want to retrieve.
+
+    Every `get` subcommand for example ``get project` without any arguments will list all projects.
+    `get project my_project` will return the details of the project named `my_project`.
+
+    In some cases `get action my_run` will return all actions for the run named `my_run` and
+    `get action my_run my_action` will return the details of the action named `my_action` for the run `my_run`.
     """
 
 
@@ -20,7 +29,7 @@ def get():
 @click.pass_obj
 def project(cfg: common.CLIConfig, name: str | None = None):
     """
-    Get the current project.
+    Retrieve a list of all projects or details of a specific project by name.
     """
     from flyte.remote import Project
 
@@ -39,7 +48,11 @@ def project(cfg: common.CLIConfig, name: str | None = None):
 @click.pass_obj
 def run(cfg: common.CLIConfig, name: str | None = None, project: str | None = None, domain: str | None = None):
     """
-    Get the current run.
+    Get list of all runs or details of a specific run by name.
+
+    The run details will include information about the run, its status, but only the root action will be shown.
+
+    If you want to see the actions for a run, use `get action <run_name>`.
     """
     from flyte.remote import Run, RunDetails
 
@@ -65,7 +78,9 @@ def task(
     domain: str | None = None,
 ):
     """
-    Get the current task.
+    Retrieve a list of all tasks or details of a specific task by name and version.
+
+    Currently name+version are required to get a specific task.
     """
     from flyte.remote import Task
 
@@ -140,8 +155,24 @@ def logs(
     filter_system: bool = False,
 ):
     """
-    Stream logs for the provided run or action. If the run is provided, only the logs for the parent action will be
-    streamed.
+    Stream logs for the provided run or action.
+    If only the run is provided, only the logs for the parent action will be streamed.
+
+    Example:
+    ```bash
+    flyte get logs my_run
+    ```
+
+    But, if you want to see the logs for a specific action, you can provide the action name as well:
+    ```bash
+    flyte get logs my_run my_action
+    ```
+    By default logs will be shown in the raw format, will scroll on the terminal. If automatic scrolling and only
+    tailing --lines lines is desired, use the `--pretty` flag:
+    ```bash
+    flyte get logs my_run my_action --pretty --lines 50
+    ```
+
     """
     import flyte.remote as remote
 
@@ -175,7 +206,7 @@ def secret(
     domain: str | None = None,
 ):
     """
-    Get the current secret.
+    Retrieve a list of all secrets or details of a specific secret by name.
     """
     import flyte.remote as remote
 
@@ -205,6 +236,19 @@ def io(
 ):
     """
     Get the inputs and outputs of a run or action.
+    if only the run name is provided, it will show the inputs and outputs of the root action of that run.
+    If an action name is provided, it will show the inputs and outputs for that action.
+
+    If `--inputs-only` or `--outputs-only` is specified, it will only show the inputs or outputs respectively.
+
+    Example:
+    ```bash
+    flyte get io my_run
+    ```
+    or
+    ```bash
+    flyte get io my_run my_action
+    ```
     """
     if inputs_only and outputs_only:
         raise click.BadParameter("Cannot use both --inputs-only and --outputs-only")
@@ -250,6 +294,8 @@ def io(
 def config(cfg: common.CLIConfig):
     """
     Shows the automatically detected configuration to connect with remote Flyte services.
+
+    The configuration will include the endpoint, organization, and other settings that are used by the CLI.
     """
     console = Console()
     console.print(cfg)

flyte/cli/_run.py

@@ -12,8 +12,6 @@ from click import Context, Parameter
 from rich.console import Console
 from typing_extensions import get_args
 
-import flyte
-
 from .._code_bundle._utils import CopyFiles
 from .._task import TaskTemplate
 from ..remote import Run
@@ -95,11 +93,19 @@ class RunTaskCommand(click.Command):
         super().__init__(obj_name, *args, **kwargs)
 
     def invoke(self, ctx: Context):
-        obj: CLIConfig = ctx.obj or CLIConfig()
-        assert obj.endpoint, "CLI Config should have an endpoint"
+        obj: CLIConfig = ctx.obj
+        if obj is None:
+            import flyte.config
+
+            obj = CLIConfig(flyte.config.auto())
+
+        if not self.run_args.local:
+            assert obj.endpoint, "CLI Config should have an endpoint"
         obj.init(self.run_args.project, self.run_args.domain)
 
         async def _run():
+            import flyte
+
             r = flyte.with_runcontext(
                 copy_style=self.run_args.copy_style,
                 version=self.run_args.copy_style,
@@ -112,8 +118,8 @@ class RunTaskCommand(click.Command):
                     common.get_panel(
                         "Run",
                         f"[green bold]Created Run: {r.name} [/green bold] "
-                        f"(Project: {r.action.action_id.run.project}, Domain: {r.action.action_id.run.domain})\n\n"
-                        f"[blue bold]{r.url}[/blue bold]",
+                        f"(Project: {r.action.action_id.run.project}, Domain: {r.action.action_id.run.domain})\n"
+                        f"➡️  [blue bold]{r.url}[/blue bold]",
                     )
                 )
                 if self.run_args.follow:
@@ -198,11 +204,31 @@ class TaskFiles(common.FileGroup):
             filename=Path(filename),
             run_args=run_args,
             name=filename,
-            help=f"Run, functions decorated `env.task` {filename}",
+            help=f"Run, functions decorated with `env.task` in {filename}",
         )
 
 
 run = TaskFiles(
     name="run",
-    help="Run a task from a python file.",
+    help="""
+Run a task from a python file.
+
+Example usage:
+```bash
+flyte run --name examples/basics/hello.py my_task --arg1 value1 --arg2 value2
+```
+Note: all arguments for the run command are provided right after the `run` command and before the file name.
+
+You can also specify the project and domain using the `--project` and `--domain` options, respectively. These
+options can be set in the config file or passed as command line arguments.
+
+Note: The arguments for the task are provided after the task name and can be retrieved using `--help`
+Example:
+```bash
+flyte run --name examples/basics/hello.py my_task --help
+```
+
+To run a task locally, use the `--local` flag. This will run the task in the local environment instead of the remote
+ Flyte environment.
+""",
 )

flyte/cli/main.py

@@ -2,14 +2,36 @@ import rich_click as click
 
 from flyte._logging import initialize_logger, logger
 
-from ..config import Config
 from ._abort import abort
 from ._common import CLIConfig
 from ._create import create
 from ._deploy import deploy
+from ._gen import gen
 from ._get import get
 from ._run import run
 
+click.rich_click.COMMAND_GROUPS = {
+    "flyte": [
+        {
+            "name": "Running Workflows",
+            "commands": ["run", "abort"],
+        },
+        {
+            "name": "Management",
+            "commands": ["create", "deploy", "get"],
+        },
+        {
+            "name": "Documentation Generation",
+            "commands": ["gen"],
+        },
+    ]
+}
+
+help_config = click.RichHelpConfiguration(
+    use_markdown=True,
+    use_markdown_emoji=True,
+)
+
 
 def _verbosity_to_loglevel(verbosity: int) -> int | None:
     """
@@ -39,18 +61,19 @@ def _verbosity_to_loglevel(verbosity: int) -> int | None:
     help="The endpoint to connect to, this will override any config and simply used pkce to connect.",
 )
 @click.option(
-    "--insecure",
+    "--insecure/--secure",
     is_flag=True,
     required=False,
-    help="insecure",
+    help="Use insecure connection to the endpoint. If secure is specified, the CLI will use TLS.",
     type=bool,
     default=None,
+    show_default=True,
 )
 @click.option(
     "-v",
     "--verbose",
     required=False,
-    help="Show verbose messages and exception traces",
+    help="Show verbose messages and exception traces, multiple times increases verbosity (e.g., -vvv).",
     count=True,
     default=0,
     type=int,
@@ -70,6 +93,7 @@ def _verbosity_to_loglevel(verbosity: int) -> int | None:
     help="Path to config file (YAML format) to use for the CLI. If not specified,"
     " the default config file will be used.",
 )
+@click.rich_config(help_config=help_config)
 @click.pass_context
 def main(
     ctx: click.Context,
@@ -80,28 +104,56 @@ def main(
     config_file: str | None,
 ):
     """
-
- ____  __    _  _  ____  ____    _  _  ____     __
-(  __)(  )  ( \\/ )(_  _)(  __)  / )( \\(___ \\   /  \
- ) _) / (_/\\ )  /   )(   ) _)   \\ \\/ / / __/ _(  0 )
-(__)  \\____/(__/   (__) (____)   \\__/ (____)(_)\\__/
+    ### Flyte entrypoint for the CLI
+    The Flyte CLI is a command line interface for interacting with Flyte.
 
     The flyte cli follows a simple verb based structure, where the top-level commands are verbs that describe the action
-to be taken, and the subcommands are nouns that describe the object of the action.
+    to be taken, and the subcommands are nouns that describe the object of the action.
+
+    The root command can be used to configure the CLI for most commands, such as setting the endpoint,
+     organization, and verbosity level.
+
+     Example: Set endpoint and organization
+     ```bash
+      flyte --endpoint <endpoint> --org <org> get project <project_name>
+     ```
+
+     Example: Increase verbosity level (This is useful for debugging, this will show more logs and exception traces)
+      ```bash
+      flyte -vvv get logs <run-name>
+      ```
+
+      Example: Override the default config file
+    ```bash
+    flyte --config /path/to/config.yaml run ...
+    ```
+
+    👉 [Documentation](https://www.union.ai/docs/flyte/user-guide/) \n
+    👉 [GitHub](https://github.com/flyteorg/flyte) - Please leave a ⭐. \n
+    👉 [Slack](https://slack.flyte.org) - Join the community and ask questions.
+    👉 [Issues](https://github.com/flyteorg/flyte/issues)
+
     """
+    import flyte.config as config
+
     log_level = _verbosity_to_loglevel(verbose)
     if log_level is not None:
         initialize_logger(log_level)
 
-    config = Config.auto(config_file=config_file)
-    logger.debug(f"Using config file discovered at location {config.source}")
+    cfg = config.auto(config_file=config_file)
+    logger.debug(f"Using config file discovered at location {cfg.source}")
+
+    final_insecure = cfg.platform.insecure
+    if insecure is not None:
+        final_insecure = insecure
 
     ctx.obj = CLIConfig(
         log_level=log_level,
-        endpoint=endpoint or config.platform.endpoint,
-        insecure=insecure or config.platform.insecure,
-        org_override=org or config.task.org,
-        config=config,
+        endpoint=endpoint or cfg.platform.endpoint,
+        insecure=final_insecure,
+        org_override=org or cfg.task.org,
+        config=cfg,
+        ctx=ctx,
     )
     logger.debug(f"Final materialized Cli config: {ctx.obj}")
 
@@ -111,3 +163,4 @@ main.add_command(deploy)
 main.add_command(get)  # type: ignore
 main.add_command(create)  # type: ignore
 main.add_command(abort)  # type: ignore
+main.add_command(gen)  # type: ignore