v1
Double column

Executing commands

You can execute commands within your service or job containers using the CLI, JavaScript client, or via the Northflank application UI.

Executing a command will normally spawn a new shell process inside the container, giving you SSH-like access to the filesystem, environment, and processes. You can explicitly specify if no shell is needed when executing a command.

You can only access the shell and execute commands on a running service or job. You can specify the container to access, otherwise a running container will be selected at random.

Execute a command using the UI

Shell access in the Northflank UI gives you access to everything inside your container, such as environment, filesystem, processes, and the ability to run commands like top, npm, sed, vi, df. It also provides command completion and command history where possible.

You can access the shell of running containers in deployment and combined services by navigating to the containers page for the specific service. You can open a shell for a specific container by clicking shell access button.

Running job containers can be accessed by navigating to the job runs page and selecting an active job run. Click shell access button on the specific container to open a shell.

Copy & paste

You can copy and paste in the browser shell with control-shift-c and control-shift-v. This may not work in Firefox, where you may need to use the right-click menu to copy and paste. Command-c and command-v works across all browsers on macOS.

Execute a command using the CLI

You can use northflank exec to run commands within your service and job containers via the CLI.

northflank exec service|job will let you select your project and service or job dynamically and then start a shell session directly in your container, similar to an SSH connection.

A command can also be specified directly: northflank exec service|job --cmd "ls -lah", which allows you to run a command without a shell. There are multiple options such as container, user and others which allows you to customise how commands are executed. You can view options with the northflank exec service|job --help command.

Execute a command using the JavaScript client

You can directly execute commands in your Northflank services and jobs with the JavaScript client.

The client exposes the exec module, which provides functionality to run commands.

Simple, short-lived command

You can run simple, short-lived commands which do not print a continuous stream of data with the following methods.

Execute a command in a service:

apiClient.exec.execServiceCommand({ projectId, serviceId }, { command: ['ls', '-lah'] })

Execute a command in a job:

apiClient.exec.execJobCommand({ projectId, jobId }, { command: ['ls', '-lah'] })

Arguments

    • command

      string | string[] required

      Command to be run

    • containerName

      string

      Container to run the command in. If not specified, a random container is used.

    • shell

      string

      Run command in shell (e.g. bash -c). If not specified, several shells are attempted.

    • user

      string | number

      Run command with specific user. If not specified, default user from image is used.

    • group

      string | number

      Run command with specific group. If not specified, default group from image is used.

Both methods return a Promise with the result of the command in the format:

Promise<{
    commandResult: {
        exitCode: number;
        status: 'Success' | 'Failure' | 'Unknown';
        message?: string;
    };
    stdOut: string;
    stdErr: string;
}>

Complex, long-running commands

You can execute long running commands which print a continuous stream of data with the following methods.

Create an execute command session in a service:

await exec.execServiceSession({ projectId, serviceId });

Create an execute command session in a job:

await exec.execJobSession({ projectId, jobId });

Arguments

    • command

      string | string[]

      Command to be run

    • containerName

      string

      Container to run the command in. If not specified, a random container is used.

    • shell

      string

      Run command in shell (e.g. bash -c). If not specified, several shells are attempted.

    • user

      string | number

      Run command with specific user. If not specified, default user from image is used.

    • group

      string | number

      Run command with specific group. If not specified, default group from image is used.

    • ttyRows

      number

      TTY height in number of rows.

    • ttyColumns

      number

      TTY width in number of columns.

Session commands return a Promise of the ExecCommand class. This exposes a number of powerful functionalities to interact with the running command: Promise<ExecCommandStandard>.

You can write to and receive data from NodeJS-compatible streams for standard input, standard output and standard error.

For example:

const execCommand = await exec.execServiceSession({ projectId: 'myproject', serviceId: 'myservice' });

execCommand.stdErr.on('data', (chunk) => console.log(chunk));
// Locally logs chunks of data from your remote service to the console

execCommand.stdIn.write('echo "hello world"');
// Executes on your remote service and prints 'hello world'

To wait for command completion, run await execCommand.waitForCommandResult());. This will return a command result with exitCode and status, similar to execServiceCommand .

© 2022 Northflank Ltd. All rights reserved.