package runme.runner.v2

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc CreateSession (CreateSessionRequest, CreateSessionResponse)

  runner.proto:371

  message CreateSessionRequest

  runner.proto:41

  • map<string, string> metadata = 1

    metadata is a map of client specific metadata.

  • repeated string env = 2

    env field provides an initial set of environment variables for a newly created session.

  • optional Project project = 3

    project from which to load environment variables. They will be appended to the list from the env field. The env field has a higher priority.

  • optional SessionEnvStoreType env_store_type = 4

    Deprecated use config instead. optional selection of which env store implementation to use.

  • optional CreateSessionRequest.Config config = 5

  message CreateSessionResponse

  runner.proto:76

  • optional Session session = 1

• rpc GetSession (GetSessionRequest, GetSessionResponse)

  runner.proto:372

  message GetSessionRequest

  runner.proto:80

  • string id = 1

  message GetSessionResponse

  runner.proto:84

  • optional Session session = 1

• rpc ListSessions (ListSessionsRequest, ListSessionsResponse)

  runner.proto:373

  message ListSessionsRequest

  runner.proto:88

  (message has no fields)

  message ListSessionsResponse

  runner.proto:90

  • repeated Session sessions = 1

• rpc UpdateSession (UpdateSessionRequest, UpdateSessionResponse)

  runner.proto:374

  message UpdateSessionRequest

  runner.proto:94

  • string id = 1

  • map<string, string> metadata = 2

    metadata is a map of client specific metadata.

  • repeated string env = 3

    env field provides an initial set of environment variables for a newly created session.

  • optional Project project = 4

    project from which to load environment variables. They will be appended to the list from the env field. The env field has a higher priority.

  message UpdateSessionResponse

  runner.proto:110

  • optional Session session = 1

• rpc DeleteSession (DeleteSessionRequest, DeleteSessionResponse)

  runner.proto:375

  message DeleteSessionRequest

  runner.proto:114

  • string id = 1

  message DeleteSessionResponse

  runner.proto:118

  (message has no fields)

• rpc MonitorEnvStore (MonitorEnvStoreRequest, stream MonitorEnvStoreResponse)

  runner.proto:377

  message MonitorEnvStoreRequest

  runner.proto:314

  • optional Session session = 1

  message MonitorEnvStoreResponse

  runner.proto:362

  • MonitorEnvStoreType type = 1

  • oneof data

    • MonitorEnvStoreResponseSnapshot snapshot = 2

• rpc Execute (stream ExecuteRequest, stream ExecuteResponse)

  runner.proto:386

  Execute executes a program. Examine "ExecuteRequest" to explore configuration options. It's a bidirectional stream RPC method. It expects the first "ExecuteRequest" to contain details of a program to execute. Subsequent "ExecuteRequest" should only contain "input_data" as other fields will be ignored.

  message ExecuteRequest

  runner.proto:144

  • optional ProgramConfig config = 1

  • bytes input_data = 8

    input_data is a byte array that will be send as input to the program.

  • ExecuteStop stop = 9

    stop requests the running process to be stopped. It is allowed only in the consecutive calls.

  • optional Winsize winsize = 10

    sets pty winsize has no effect in non-interactive mode

  • string session_id = 20

    session_id indicates in which Session the program should execute. Executing in a Session might provide additional context like environment variables.

  • SessionStrategy session_strategy = 21

    session_strategy is a strategy for selecting the session.

  • optional Project project = 22

    project used to load environment variables from .env files.

  • bool store_stdout_in_env = 23

    store_stdout_in_env, if true, will store the stdout under well known name and the last ran block in the environment variable `__`.

  message ExecuteResponse

  runner.proto:175

  • optional google.protobuf.UInt32Value exit_code = 1

    exit_code is sent only in the final message.

  • bytes stdout_data = 2

    stdout_data contains bytes from stdout since the last response.

  • bytes stderr_data = 3

    stderr_data contains bytes from stderr since the last response.

  • optional google.protobuf.UInt32Value pid = 4

    pid contains the process' PID. This is only sent once in an initial response for background processes.

  • string mime_type = 5

    mime_type is a detected MIME type of the stdout_data. This is only sent once in the first response containing stdout_data.

• rpc ResolveProgram (ResolveProgramRequest, ResolveProgramResponse)

  runner.proto:392

  ResolveProgram resolves variables from a script or a list of commands using the provided sources, which can be a list of environment variables, a session, or a project. For now, the resolved variables are only the exported ones using `export`.

  message ResolveProgramRequest

  runner.proto:203

  • oneof source

    use script for unnormalized cell content whereas commands is for normalized shell commands

    • ResolveProgramCommandList commands = 1

      commands are commands to be executed by the program. The commands are joined and executed as a script.

    • string script = 2

      script is code to be executed by the program. Individual lines are joined with the new line character.

  • ResolveProgramRequest.Mode mode = 3

    mode determines how variables resolution occurs. It is usually based on document or cell annotation config.

  • repeated string env = 4

    env is a list of explicit environment variables that will be used to resolve the environment variables found in the source.

  • string session_id = 5

    session_id indicates which session is the source of environment variables. If not provided, the most recent session can be used using session_strategy.

  • SessionStrategy session_strategy = 6

    session_strategy is a strategy for selecting the session.

  • optional Project project = 7

    project used to load environment variables from .env files.

  • string language_id = 8

    language id associated with script.

  • ResolveProgramRequest.Retention retention = 9

    retention determines how variables are retained once resolved.

  message ResolveProgramResponse

  runner.proto:264

  • string script = 1

  • optional ResolveProgramCommandList commands = 2

    use script until commands normalization is implemented

  • repeated ResolveProgramResponse.VarResult vars = 3

Used in: ProgramConfig

• COMMAND_MODE_UNSPECIFIED = 0

• COMMAND_MODE_INLINE = 1

  COMMAND_MODE_INLINE indicates that the command should be executed inline. For example: bash -c "echo 'Hello, World'"

• COMMAND_MODE_FILE = 2

  COMMAND_MODE_FILE indicates that the command should be executed as a file. For example: bash /tmp/script.sh

• COMMAND_MODE_TERMINAL = 3

  COMMAND_MODE_TERMINAL indicates that the command should be executed as a Runme Terminal. This is used by the VS Code extension.

• COMMAND_MODE_CLI = 4

  COMMAND_MODE_CLI indicates that the command is executed via runme CLI. It is executed as a native command.

Used in: CreateSessionRequest

• optional SessionEnvStoreType env_store_type = 1

  optional selection of which env store implementation to use.

• optional Config.SessionEnvStoreSeeding env_store_seeding = 2

  how to seed initial ENV

Used in: Config

• SESSION_ENV_STORE_SEEDING_UNSPECIFIED = 0

  default seeding; ignore system

• SESSION_ENV_STORE_SEEDING_SYSTEM = 1

  enable seeding from system

Used in: ExecuteRequest

• EXECUTE_STOP_UNSPECIFIED = 0

• EXECUTE_STOP_INTERRUPT = 1

• EXECUTE_STOP_KILL = 2

Used in: MonitorEnvStoreResponse

• repeated MonitorEnvStoreResponseSnapshot.SnapshotEnv envs = 1

Used in: SnapshotEnv

• uint32 code = 1

• string message = 2

Used in: MonitorEnvStoreResponseSnapshot

• Status status = 1

• string name = 2

• string description = 3

• string spec = 4

• bool is_required = 5

• string origin = 6

• string original_value = 7

• string resolved_value = 8

• string create_time = 9

• string update_time = 10

• repeated Error errors = 11

Used in: SnapshotEnv

• STATUS_UNSPECIFIED = 0

• STATUS_LITERAL = 1

• STATUS_HIDDEN = 2

• STATUS_MASKED = 3

Used in: MonitorEnvStoreResponse

• MONITOR_ENV_STORE_TYPE_UNSPECIFIED = 0

• MONITOR_ENV_STORE_TYPE_SNAPSHOT = 1

  possible expansion to have a "timeline" view MONITOR_ENV_STORE_TYPE_TIMELINE = 2;

ProgramConfig is a configuration for a program to execute. From this configuration, any program can be built.

Used in: ExecuteRequest

• string program_name = 1

  program_name is a name of the program to execute. If it's not a path (relative or absolute), the runner will try to resolve the name. For example: "sh", "/bin/bash".

• repeated string arguments = 2

  arguments is a list of arguments passed to the program.

• string directory = 3

  directory to execute the program in.

• string language_id = 4

  language_id associated with script to allow interpreter detection if no specific interpreter program is provided.

• bool background = 5

  background indicates a background process required to handle running background tasks via CLI in C/I

• string file_extension = 6

  file_extension associated with script. Some interpreters are strict about file extensions, such as tsc which requires "ts" extension.

• repeated string env = 7

  env is a list of additional environment variables that will be injected to the executed program.

• oneof source

  • ProgramConfig.CommandList commands = 8

    commands are commands to be executed by the program. The commands are joined and executed as a script.

  • string script = 9

    script is code to be executed by the program. Individual lines are joined with the new line character.

• bool interactive = 10

  interactive, if true, uses a pseudo-tty to execute the program. Otherwise, the program is executed using in-memory buffers for I/O.

• CommandMode mode = 11

  TODO(adamb): understand motivation for this. In theory, source should tell whether to execute it inline or as a file.

• string known_id = 12

  optional well known id for cell/block

• string known_name = 13

  optional well known name for cell/block

Used in: ProgramConfig

• repeated string items = 1

  commands are commands to be executed by the program. The commands are joined and executed as a script. For example: ["echo 'Hello, World'", "ls -l /etc"].

Used in: CreateSessionRequest, ExecuteRequest, ResolveProgramRequest, UpdateSessionRequest

• string root = 1

  root is a root directory of the project. The semantic is the same as for the "--project" flag in "runme".

• repeated string env_load_order = 2

  env_load_order is list of environment files to try and load env from.

Used in: ResolveProgramRequest, ResolveProgramResponse

• repeated string lines = 1

  commands are commands to be executed by the program. The commands are joined and executed as a script. For example: ["echo 'Hello, World'", "ls -l /etc"].

Used in: ResolveProgramRequest

• MODE_UNSPECIFIED = 0

  unspecified is auto (default) which prompts for all unresolved environment variables. Subsequent runs will likely resolve via the session.

• MODE_PROMPT_ALL = 1

  prompt always means to prompt for all environment variables.

• MODE_SKIP_ALL = 2

  skip means to not prompt for any environment variables. All variables will be marked as resolved.

Used in: ResolveProgramRequest

• RETENTION_UNSPECIFIED = 0

• RETENTION_FIRST_RUN = 1

  first run means to always retain the first resolved value.

• RETENTION_LAST_RUN = 2

  last run means to always retain the last resolved value.

Used in: VarResult

• STATUS_UNSPECIFIED = 0

  unspecified is the default value and it means unresolved.

• STATUS_RESOLVED = 1

  resolved means that the variable is resolved.

• STATUS_UNRESOLVED_WITH_MESSAGE = 2

  unresolved with message means that the variable is unresolved but it contains a message. E.g. FOO=this is message.

• STATUS_UNRESOLVED_WITH_PLACEHOLDER = 3

  unresolved with placeholder means that the variable is unresolved but it contains a placeholder. E.g. FOO="this is placeholder".

• STATUS_UNRESOLVED_WITH_SECRET = 4

  unresolved with secret means that the variable is unresolved and it requires treatment as a secret.

Used in: ResolveProgramResponse

• Status status = 1

  prompt indicates the resolution status of the env variable.

• string name = 2

  name is the name of the environment variable.

• string original_value = 3

  original_value is a default value of the environment variable. It might be a value that is assigned to the variable in the script, like FOO=bar or FOO=${FOO:-bar}. If the variable is not assigned, it is an empty string.

• string resolved_value = 4

  resolved_value is a value of the environment variable resolved from a source. If it is an empty string, it means that the environment variable is not resolved.

Used in: CreateSessionResponse, GetSessionResponse, ListSessionsResponse, MonitorEnvStoreRequest, UpdateSessionResponse

• string id = 1

• repeated string env = 2

  env keeps track of session environment variables. They can be modified by executing programs which alter them through "export" and "unset" commands.

• map<string, string> metadata = 3

  metadata is a map of client specific metadata.

env store implementation

Used in: CreateSessionRequest, CreateSessionRequest.Config

• SESSION_ENV_STORE_TYPE_UNSPECIFIED = 0

  uses default env store

• SESSION_ENV_STORE_TYPE_OWL = 1

  uses owl store

SessionStrategy determines a session selection in an initial execute request.

Used in: ExecuteRequest, ResolveProgramRequest

• SESSION_STRATEGY_UNSPECIFIED = 0

  Uses the session_id field to determine the session. If none is present, a new session is created.

• SESSION_STRATEGY_MOST_RECENT = 1

  Uses the most recent session on the server. If there is none, a new one is created.

Used in: ExecuteRequest

• uint32 rows = 1

• uint32 cols = 2

• uint32 x = 3

• uint32 y = 4